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

X-API-KEYstringRequired

Responses

200

Metadata object

application/json

get

/v1/meta

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

X-API-KEYstringRequired

Responses

200

A list of model names

application/json

Responsestring[]

get

/v1/meta/models

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

X-API-KEYstringRequired

Responses

200

A list of image model names

application/json

Responsestring[]

get

/v1/meta/image_models

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

X-API-KEYstringRequired

Responses

200

A list of supported languages

application/json

get

/v1/meta/languages

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

X-API-KEYstringRequired

Responses

200

A list of supported regions

application/json

get

/v1/meta/regions

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

X-API-KEYstringRequired

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

/v1/images

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

X-API-KEYstringRequired

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

/v1/images

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

X-API-KEYstringRequired

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

/v1/contents

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-12-18T14:49:36.915Z",
    "updated_at": "2025-12-18T14:49:36.915Z"
  }
]

Create a new article

post

Authorizations

X-API-KEYstringRequired

Body

target_keywordstringRequired

The target_keyword for the article.

modelstringOptional

The model to use for the article.

Default: gpt-4o-mini

settings_presetnumber | nullableOptional

The settings preset to use for the article. Use the settings object to override specific settings. Go to your presets to create a preset.

is_draftbooleanOptional

Whether the article is a draft

Default: false

Responses

200

Article created successfully

application/json

post

/v1/contents

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

{
  "target_keyword": "text",
  "model": "gpt-4o-mini",
  "outline": [
    {
      "type": "heading",
      "level": 2,
      "title": "text"
    }
  ],
  "settings_preset": 1,
  "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

X-API-KEYstringRequired

Path parameters

idstringRequired

The ID of the article

Responses

200

The article object

application/json

get

/v1/contents/{id}

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-12-18T14:49:36.915Z",
  "updated_at": "2025-12-18T14:49:36.915Z"
}

Get the current status of an article

get

Authorizations

X-API-KEYstringRequired

Path parameters

idstringRequired

The ID of the article

Responses

200

The status of the article

application/json

get

/v1/contents/{id}/status

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

X-API-KEYstringRequired

Responses

200

A list of projects

application/json

get

/v1/projects

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-12-18T14:49:36.915Z",
    "updated_at": "2025-12-18T14:49:36.915Z"
  }
]

Create a new project

post

Authorizations

X-API-KEYstringRequired

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

common_settings_presetnumber | nullableOptional

The settings preset to use for the project. Use the common_settings object to override specific settings. Go to your presets to create a preset.

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

The target keywords to generate content for.

Responses

200

Project created successfully

application/json

post

/v1/projects

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

{
  "project_name": "text",
  "model": "gpt-4o-mini",
  "common_settings_preset": 1,
  "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-12-18T14:49:36.915Z",
  "updated_at": "2025-12-18T14:49:36.915Z"
}

Get a project by ID

get

Authorizations

X-API-KEYstringRequired

Path parameters

idstringRequired

The ID of the project

Responses

200

The project object

application/json

get

/v1/projects/{id}

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-12-18T14:49:36.915Z",
  "updated_at": "2025-12-18T14:49:36.915Z"
}

PreviousEnterprise Builds NextWebhooks

Last updated 7 months ago

Was this helpful?