API reference

Available on Business and above.

Use the Cuppa API to generate content and images using AI. The capabilities of the API are defined in the next sections.

Authentication

To use the API, you need to authenticate using an API key. Go to your Cuppa settings to obtain an API key. Include the API key in the X-API-KEY header of your requests as follows:

curl -X GET "https://api.cuppa.ai/v1/meta" \
  -H "accept: application/json" \
  -H "X-API-KEY: YOUR_API_KEY"

Rate Limiting

The API has rate limits in place to ensure fair usage.

Error Handling

The API returns standard HTTP status codes to indicate the success or failure of a request. In case of an error, the response will contain an error object with details about the error.

Get all metadata

get

Authorizations

Responses

200

Metadata object

application/json

get

HTTPcURLJavaScriptPython

GET /v1/meta HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

Metadata object

{
  "languages": [
    {
      "name": "text",
      "code": "text"
    }
  ],
  "regions": [
    {
      "name": "text",
      "code": "text"
    }
  ],
  "models": [
    "text"
  ],
  "image_models": [
    "text"
  ]
}

Get available models

get

Authorizations

Responses

200

A list of model names

application/json

Responsestring[]

get

HTTPcURLJavaScriptPython

GET /v1/meta/models HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

A list of model names

[
  "text"
]

Get available image models

get

Authorizations

Responses

200

A list of image model names

application/json

Responsestring[]

get

HTTPcURLJavaScriptPython

GET /v1/meta/image_models HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

A list of image model names

[
  "text"
]

Get available languages

get

Authorizations

Responses

200

A list of supported languages

application/json

get

HTTPcURLJavaScriptPython

GET /v1/meta/languages HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

A list of supported languages

[
  {
    "name": "text",
    "code": "text"
  }
]

Get available regions

get

Authorizations

Responses

200

A list of supported regions

application/json

get

HTTPcURLJavaScriptPython

GET /v1/meta/regions HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

A list of supported regions

[
  {
    "name": "text",
    "code": "text"
  }
]

Fetch list of generated images

get

Authorizations

Query parameters

limitinteger · max: 50Optional

Maximum number of images to return (max 50, default 20)

Responses

200

A list of generated images

application/json

get

HTTPcURLJavaScriptPython

GET /v1/images HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

A list of generated images

[
  {
    "id": "text",
    "url": "text"
  }
]

Create an image

post

Authorizations

Body

modelstringRequired

The model to use for image generation. Use the /v1/meta/image_models endpoint to get available image models.

promptstring · max: 1000Required

The prompt to use for image generation

Responses

200

Successfully generated image

application/json

post

HTTPcURLJavaScriptPython

POST /v1/images HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 86

{
  "model": "text",
  "prompt": "text",
  "settings": {
    "size": "1792x1024",
    "aspect_ratio": "16:9"
  }
}

200

Successfully generated image

{
  "id": "text",
  "url": "text"
}

Fetch list of articles

get

Authorizations

Query parameters

pageinteger | nullableOptional

Page number for pagination

langstring | nullableOptional

Filter by language code

projectstring | nullableOptional

Filter by project ID. If not provided, it will return the articles not part of any project. Use all to get all articles.

Responses

200

A list of articles

application/json

get

HTTPcURLJavaScriptPython

GET /v1/contents HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

A list of articles

[
  {
    "id": "text",
    "is_draft": true,
    "status": "initializing",
    "title": "text",
    "content": "text",
    "snippet": "text",
    "project_id": "text",
    "meta_description": "text",
    "featured_images": [
      {
        "url": "text",
        "alt": "text"
      }
    ],
    "content_type": "article",
    "settings": {
      "model": "text",
      "target_keyword": "text",
      "language": "text",
      "region": "text"
    },
    "created_at": "2025-05-19T09:35:06.713Z",
    "updated_at": "2025-05-19T09:35:06.713Z"
  }
]

Create a new article

post

Authorizations

Body

target_keywordstringRequired

The target_keyword for the article.

modelstringOptional

The model to use for the article.

Default: gpt-4o-mini

is_draftbooleanOptional

Whether the article is a draft

Default: false

Responses

200

Article created successfully

application/json

post

HTTPcURLJavaScriptPython

POST /v1/contents HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 772

{
  "target_keyword": "text",
  "model": "gpt-4o-mini",
  "outline": [
    {
      "type": "heading",
      "level": 2,
      "title": "text"
    }
  ],
  "settings": {
    "language": "text",
    "region": "text",
    "tone": "seo_optimized",
    "pov": "first_person_plural",
    "article_type": "general",
    "fetch_perplexity": false,
    "include_introduction": true,
    "include_conclusion": true,
    "include_yt_suggestions": false,
    "generate_faqs": false,
    "generate_meta_description": false,
    "key_takeaways_position": "none",
    "include_stock_images": false,
    "generate_images": false,
    "image_settings": {
      "model": "dall-e-3",
      "max_body_images_count": 1,
      "style_preset": "photorealistic",
      "custom_style": {
        "name": "text",
        "description": "text"
      }
    },
    "advanced_settings": {
      "title_prompt": "text",
      "introduction_prompt": "text",
      "section_prompt": "text",
      "meta_description_prompt": "text"
    }
  },
  "is_draft": false
}

200

Article created successfully

{
  "id": "text",
  "is_draft": true,
  "status": "initializing",
  "status_extra": {
    "error": "text"
  }
}

Get an article by ID

get

Authorizations

Path parameters

idstringRequired

The ID of the article

Responses

200

The article object

application/json

get

HTTPcURLJavaScriptPython

GET /v1/contents/{id} HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

The article object

{
  "id": "text",
  "is_draft": true,
  "status": "initializing",
  "title": "text",
  "content": "text",
  "snippet": "text",
  "project_id": "text",
  "meta_description": "text",
  "featured_images": [
    {
      "url": "text",
      "alt": "text"
    }
  ],
  "content_type": "article",
  "settings": {
    "model": "text",
    "target_keyword": "text",
    "language": "text",
    "region": "text"
  },
  "created_at": "2025-05-19T09:35:06.713Z",
  "updated_at": "2025-05-19T09:35:06.713Z"
}

Get the current status of an article

get

Authorizations

Path parameters

idstringRequired

The ID of the article

Responses

200

The status of the article

application/json

get

HTTPcURLJavaScriptPython

GET /v1/contents/{id}/status HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

The status of the article

{
  "id": "text",
  "is_draft": true,
  "status": "initializing",
  "status_extra": {
    "error": "text"
  }
}

Fetch list of projects

get

Authorizations

Responses

200

A list of projects

application/json

get

HTTPcURLJavaScriptPython

GET /v1/projects HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

A list of projects

[
  {
    "id": "text",
    "name": "text",
    "created_at": "2025-05-19T09:35:06.713Z",
    "updated_at": "2025-05-19T09:35:06.713Z"
  }
]

Create a new project

post

Authorizations

Body

project_namestring · max: 100Required

Name of the project

modelstringOptional

The model to use for the article. Use the /v1/meta/models endpoint to get available models.

Default: gpt-4o-mini

target_keywordsstring[] · min: 1 · max: 20Required

The target keywords to generate content for.

Responses

200

Project created successfully

application/json

post

HTTPcURLJavaScriptPython

POST /v1/projects HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 731

{
  "project_name": "text",
  "model": "gpt-4o-mini",
  "common_settings": {
    "language": "text",
    "region": "text",
    "tone": "seo_optimized",
    "pov": "first_person_plural",
    "article_type": "general",
    "fetch_perplexity": false,
    "include_introduction": true,
    "include_conclusion": true,
    "include_yt_suggestions": false,
    "generate_faqs": false,
    "generate_meta_description": false,
    "key_takeaways_position": "none",
    "include_stock_images": false,
    "generate_images": false,
    "image_settings": {
      "model": "dall-e-3",
      "max_body_images_count": 1,
      "style_preset": "photorealistic",
      "custom_style": {
        "name": "text",
        "description": "text"
      }
    },
    "advanced_settings": {
      "title_prompt": "text",
      "introduction_prompt": "text",
      "section_prompt": "text",
      "meta_description_prompt": "text"
    }
  },
  "target_keywords": [
    "text"
  ]
}

200

Project created successfully

{
  "id": "text",
  "name": "text",
  "articles": {
    "ANY_ADDITIONAL_PROPERTY": "initializing"
  },
  "created_at": "2025-05-19T09:35:06.713Z",
  "updated_at": "2025-05-19T09:35:06.713Z"
}

Get a project by ID

get

Authorizations

Path parameters

idstringRequired

The ID of the project

Responses

200

The project object

application/json

get

HTTPcURLJavaScriptPython

GET /v1/projects/{id} HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

The project object

{
  "id": "text",
  "name": "text",
  "articles": {
    "ANY_ADDITIONAL_PROPERTY": "initializing"
  },
  "created_at": "2025-05-19T09:35:06.713Z",
  "updated_at": "2025-05-19T09:35:06.713Z"
}