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.

Get all metadata

get

Authorizations

X-API-KEYstringRequired

Responses

200

Metadata object

application/json

modelsstring[]Required

image_modelsstring[]Required

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

string[]Optional

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

Returns all available image generation models. Models are grouped by provider:

OpenAI models (require OpenAI API key):

gpt-image-1: GPT Image 1, photorealistic quality. Sizes: 1024x1024, 1536x1024, 1024x1536

Replicate models (require Replicate API key):

black-forest-labs/flux-1.1-pro-ultra: Flux 1.1 Pro Ultra, highest quality Flux model
black-forest-labs/flux-1.1-pro: Flux 1.1 Pro, high quality with custom dimensions
black-forest-labs/flux-dev: Flux Dev, fast iteration
black-forest-labs/flux-pro: Flux Pro, balanced quality and speed
black-forest-labs/flux-schnell: Flux Schnell, fastest Flux model
stability-ai/stable-diffusion-3: Stable Diffusion 3
replicate:nano-banana-pro: Nano Banana Pro, supports 1K/2K/4K resolution output
replicate:imagen-4: Google Imagen 4 via Replicate

Google models (require Google AI API key):

imagen-4.0-generate-001: Google Imagen 4, native Google API

Authorizations

X-API-KEYstringRequired

Responses

200

A list of image model names

application/json

string[]OptionalExample:

["gpt-image-1","black-forest-labs/flux-1.1-pro-ultra","black-forest-labs/flux-1.1-pro","black-forest-labs/flux-dev","black-forest-labs/flux-pro","black-forest-labs/flux-schnell","stability-ai/stable-diffusion-3","replicate:nano-banana-pro","replicate:imagen-4","imagen-4.0-generate-001"]

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

[
  "gpt-image-1",
  "black-forest-labs/flux-1.1-pro-ultra",
  "black-forest-labs/flux-1.1-pro",
  "black-forest-labs/flux-dev",
  "black-forest-labs/flux-pro",
  "black-forest-labs/flux-schnell",
  "stability-ai/stable-diffusion-3",
  "replicate:nano-banana-pro",
  "replicate:imagen-4",
  "imagen-4.0-generate-001"
]

Get available languages

get

Authorizations

X-API-KEYstringRequired

Responses

200

A list of supported languages

application/json

namestringRequired

codestringRequired

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

namestringRequired

codestringRequired

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

idstringRequired

urlstringRequired

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 the full list. OpenAI models use the size setting. Replicate/Google models use the aspect_ratio setting.

Example: gpt-image-1

promptstring · max: 1000Required

The prompt to use for image generation

Responses

200

Successfully generated image

application/json

idstringOptional

urlstringOptional

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: 111

{
  "model": "gpt-image-1",
  "prompt": "text",
  "settings": {
    "size": "1536x1024",
    "aspect_ratio": "16:9",
    "resolution": "1K"
  }
}

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.

sitestring · uuid · nullableOptional

Filter by site/brand ID. Use GET /v1/sites to get available site IDs.

Responses

200

A list of articles

application/json

idstringOptional

is_draftbooleanOptional

Whether the article is a draft

statusstring · enumOptionalPossible values:

titlestring · nullableOptional

It is null if the article is not generated yet.

contentstring · nullableOptional

It is null if the article is not generated yet.

snippetstring · nullableOptional

project_idstring · nullableOptional

It is null if the article is not part of a project.

site_idstring · uuid · nullableOptional

The site/brand ID associated with this article. Null if no brand context.

meta_descriptionstring · nullableOptional

content_typestring · enumOptionalPossible values:

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

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",
    "site_id": "123e4567-e89b-12d3-a456-426614174000",
    "meta_description": "text",
    "featured_images": [
      {
        "url": "text",
        "alt": "text"
      }
    ],
    "content_type": "article",
    "settings": {
      "model": "text",
      "target_keyword": "text",
      "language": "text",
      "region": "text"
    },
    "created_at": "2026-03-21T17:40:42.691Z",
    "updated_at": "2026-03-21T17:40:42.691Z"
  }
]

Create a new article

post

Create content using different templates:

article (default): Full-featured articles with support for listicles, reviews, how-tos. Use settings.article_type to specify.
local_news: Location-focused news articles. Simpler settings, uses local_news_settings.
recipe: Structured recipe content with ingredients, instructions. Uses recipe_settings.

Authorizations

X-API-KEYstringRequired

Body

target_keywordstringRequired

The target keyword for the content.

templatestring · enumOptional

The content template to use:

article: General articles with full settings (listicle, review, howto, general)
local_news: Location-focused news content
recipe: Structured recipe with ingredients and instructions

Default: articlePossible values:

site_idstring · uuid · nullableOptional

Optional site/brand ID. When provided, enables Brand Voice, site context, target audience, and Link Engine. Pass null to explicitly create content without any brand context (Organization Mode). When omitted, auto-assigns your default site.

modelstringOptional

The AI model to use.

Default: gpt-4o-mini

settings_presetnumber · nullableOptional

Preset ID (only for template=article).

use_serpbooleanOptional

When true, fetches top SERP competitors before generation and uses their content as context to write a more competitive article. Requires a Power plan or higher.

Default: false

is_draftbooleanOptional

Whether to save as draft (won't generate immediately)

Default: false

Responses

200

Content created successfully

application/json

idstringOptional

is_draftbooleanOptional

Whether the article is a draft

statusstring · enumOptionalPossible values:

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: 1000

{
  "target_keyword": "text",
  "template": "article",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "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": "gpt-image-1",
      "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"
    }
  },
  "local_news_settings": {
    "target_audience": "text",
    "extra_prompt": "text"
  },
  "recipe_settings": {
    "recipe_template": "modern"
  },
  "use_serp": false,
  "is_draft": false
}

200

Content 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

idstringOptional

is_draftbooleanOptional

Whether the article is a draft

statusstring · enumOptionalPossible values:

titlestring · nullableOptional

It is null if the article is not generated yet.

contentstring · nullableOptional

It is null if the article is not generated yet.

snippetstring · nullableOptional

project_idstring · nullableOptional

It is null if the article is not part of a project.

site_idstring · uuid · nullableOptional

The site/brand ID associated with this article. Null if no brand context.

meta_descriptionstring · nullableOptional

content_typestring · enumOptionalPossible values:

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

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",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "meta_description": "text",
  "featured_images": [
    {
      "url": "text",
      "alt": "text"
    }
  ],
  "content_type": "article",
  "settings": {
    "model": "text",
    "target_keyword": "text",
    "language": "text",
    "region": "text"
  },
  "created_at": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z"
}

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

idstringOptional

is_draftbooleanOptional

Whether the article is a draft

statusstring · enumOptionalPossible values:

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"
  }
}

Get content grade for an article

get

Returns the content grade and SERP optimization scores for an article. Requires Power plan or higher.

Authorizations

X-API-KEYstringRequired

Path parameters

idstringRequired

The article ID

Responses

200

Article grade

application/json

existsbooleanOptional

get

/v1/contents/{id}/grade

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

200

Article grade

{
  "grade": {
    "overall_score": 1,
    "seo_score": 1,
    "readability_score": 1,
    "slop_score": 1,
    "ai_search_score": 1,
    "structure_score": 1,
    "technical_score": 1,
    "word_count": 1,
    "target_keyword": "text",
    "graded_at": "2026-03-21T17:40:42.691Z",
    "grader_version": "text",
    "has_serp_data": true,
    "serp_score": {
      "overall": 1,
      "term_coverage": 1,
      "intent_alignment": 1,
      "structure_match": 1,
      "paa_coverage": 1
    }
  },
  "exists": true
}

Trigger grading for an article

post

Analyzes the article and generates a content grade. Requires Power plan or higher.

Authorizations

X-API-KEYstringRequired

Path parameters

idstringRequired

The article ID

Responses

200

Article graded successfully

application/json

existsbooleanOptional

post

/v1/contents/{id}/grade

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

200

Article graded successfully

{
  "grade": {
    "overall_score": 1,
    "seo_score": 1,
    "readability_score": 1,
    "slop_score": 1,
    "ai_search_score": 1,
    "structure_score": 1,
    "technical_score": 1,
    "word_count": 1,
    "target_keyword": "text",
    "graded_at": "2026-03-21T17:40:42.691Z",
    "grader_version": "text",
    "has_serp_data": true,
    "serp_score": {
      "overall": 1,
      "term_coverage": 1,
      "intent_alignment": 1,
      "structure_match": 1,
      "paa_coverage": 1
    }
  },
  "exists": true
}

Get SERP analysis data for an article

get

Returns competitor analysis data including top-ranking pages, word counts, and search intent. Requires Power plan or higher.

Authorizations

X-API-KEYstringRequired

Path parameters

idstringRequired

The article ID

Responses

200

SERP analysis data

application/json

statusstring · enumOptionalPossible values:

get

/v1/contents/{id}/serp

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

200

SERP analysis data

{
  "serp_data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "article_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "pending",
    "target_keyword": "text",
    "location": "text",
    "competitor_count": 1,
    "avg_word_count": 1,
    "keyword_intent": "informational",
    "paa_questions": [
      "text"
    ],
    "top_competitors": [
      {
        "rank": 1,
        "url": "text",
        "title": "text",
        "word_count": 1
      }
    ],
    "created_at": "2026-03-21T17:40:42.691Z",
    "updated_at": "2026-03-21T17:40:42.691Z"
  },
  "status": "not_fetched"
}

Fetch SERP data for an article

post

Triggers competitor analysis by scraping top 10 search results for the article's keyword. Data is cached for 3 days. Requires Power plan or higher.

Authorizations

X-API-KEYstringRequired

Path parameters

idstringRequired

The article ID

Body

locationstringOptional

Country/region code (e.g. "us", "uk"). Required if not set on article.

Responses

200

SERP fetch started

application/json

messagestringOptional

statusstringOptional

article_idstringOptional

post

/v1/contents/{id}/serp

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

{
  "location": "text"
}

200

SERP fetch started

{
  "message": "text",
  "status": "text",
  "article_id": "text"
}

Get AI optimization suggestions

post

Generates actionable suggestions to improve content based on SERP competitor analysis. Requires SERP data to be fetched first (POST /v1/contents/{id}/serp). Uses Anthropic API key if available for AI-powered suggestions, otherwise returns quick suggestions. Requires Power plan or higher.

Authorizations

X-API-KEYstringRequired

Path parameters

idstringRequired

The article ID

Body

use_aibooleanOptional

Use AI for suggestions (requires Anthropic API key)

Default: true

Responses

200

Optimization suggestions

application/json

AI-powered optimization suggestions based on SERP analysis

modestring · enumOptional

Whether AI or quick rule-based suggestions were used

Possible values:

summarystringOptional

estimated_score_improvementintegerOptional

post

/v1/contents/{id}/optimize

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

{
  "use_ai": true
}

200

Optimization suggestions

{
  "mode": "ai",
  "summary": "text",
  "estimated_score_improvement": 1,
  "suggestions": [
    {
      "id": "text",
      "type": "content",
      "priority": "high",
      "title": "text",
      "description": "text",
      "content": "text",
      "location": "text",
      "impact_score": 1,
      "terms": [
        "text"
      ]
    }
  ],
  "serp_analysis": {
    "overall_score": 1,
    "term_coverage": 1,
    "intent_alignment": 1,
    "structure_match": 1,
    "paa_coverage": 1,
    "missing_terms": [
      "text"
    ],
    "missing_topics": [
      "text"
    ],
    "unanswered_questions": [
      "text"
    ]
  }
}

Fetch list of projects

get

Authorizations

X-API-KEYstringRequired

Responses

200

A list of projects

application/json

idstringOptional

namestringOptional

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

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": "2026-03-21T17:40:42.691Z",
    "updated_at": "2026-03-21T17:40:42.691Z"
  }
]

Create a new project

post

Authorizations

X-API-KEYstringRequired

Body

project_namestring · max: 100Required

Name of the project

site_idstring · uuid · nullableOptional

Optional site/brand ID. When provided, enables Brand Voice, site context, target audience, and Link Engine for all articles in the project. Use GET /v1/sites to list available sites.

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

idstringOptional

namestringOptional

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

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: 810

{
  "project_name": "text",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "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": "gpt-image-1",
      "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": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z"
}

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

idstringOptional

namestringOptional

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

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": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z"
}

Export project articles

get

Export all completed articles from a project in JSON or CSV format. This endpoint is useful for bulk exporting content to external systems like Airtable, spreadsheets, or custom CMS integrations.

Authorizations

X-API-KEYstringRequired

Path parameters

idstringRequired

The ID of the project to export

Query parameters

formatstring · enumOptional

The export format. Use csv for spreadsheet-compatible output.

Default: jsonPossible values:

fieldsstringOptional

Comma-separated list of fields to include in the export. Available fields: title, slug, content, excerpt, date, image, target_keyword, keywords, language, model, pov, tone. Default: title,slug,content,excerpt,image,target_keyword,language,model

session_idstring · nullableOptional

Filter articles by bulk session ID (optional)

statusstring · enumOptional

Filter by article status. Use complete to only export finished articles, or all to include in-progress articles.

Default: completePossible values:

Responses

200

Exported articles

404

No articles found for this project

application/json

get

/v1/projects/{id}/export

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

{
  "articles": [
    {
      "title": "text",
      "slug": "text",
      "content": "text",
      "excerpt": "text",
      "date": "2026-03-21T17:40:42.691Z",
      "image": "text",
      "target_keyword": "text",
      "keywords": "text",
      "language": "text",
      "model": "text",
      "pov": "text",
      "tone": "text"
    }
  ]
}

List all sites/brands

get

Returns a list of all sites (brands) for your team. Use site IDs when creating content to enable Brand DNA features.

Authorizations

X-API-KEYstringRequired

Query parameters

pageintegerOptional

Page number for pagination

Responses

200

A list of sites

application/json

idstring · uuidOptional

domainstringOptional

The domain/URL of the site

icon_urlstring · nullableOptional

URL to the site favicon or icon

statusstring · enumOptionalPossible values:

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

get

/v1/sites

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

200

A list of sites

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "text",
    "icon_url": "text",
    "status": "active",
    "created_at": "2026-03-21T17:40:42.691Z",
    "updated_at": "2026-03-21T17:40:42.691Z"
  }
]

Get a site by ID

get

Authorizations

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The site ID

Responses

200

The site object

application/json

idstring · uuidOptional

domainstringOptional

The domain/URL of the site

icon_urlstring · nullableOptional

URL to the site favicon or icon

statusstring · enumOptionalPossible values:

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

get

/v1/sites/{id}

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

200

The site object

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "domain": "text",
  "icon_url": "text",
  "status": "active",
  "created_at": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z"
}

Get all brand information for a site

get

Returns brand context, voices, and visual style in a single request.

Authorizations

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The site ID

Responses

200

Brand information

application/json

get

/v1/sites/{id}/brand

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

200

Brand information

{
  "context": {
    "company_name": "text",
    "description": "text",
    "industry": "text",
    "target_audience": "text",
    "value_proposition": "text",
    "competitors": {},
    "ranking_keywords": {},
    "pain_points": {},
    "faq_questions": {}
  },
  "voices": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "is_active": true,
      "values": {}
    }
  ],
  "visual_style": {
    "logo_url": "text",
    "primary_color": "text",
    "secondary_color": "text",
    "accent_color": "text",
    "primary_font": "text",
    "visual_mood": "text"
  }
}

List all presets

get

Returns a list of AI instruction presets that can be used when creating content.

Authorizations

X-API-KEYstringRequired

Query parameters

pageintegerOptional

Page number for pagination

Responses

200

A list of presets

application/json

idintegerOptional

namestringOptional

descriptionstring · nullableOptional

target_content_typestring · enum · nullableOptionalPossible values:

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

get

/v1/presets

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

200

A list of presets

[
  {
    "id": 1,
    "name": "text",
    "description": "text",
    "target_content_type": "general",
    "created_at": "2026-03-21T17:40:42.691Z",
    "updated_at": "2026-03-21T17:40:42.691Z"
  }
]

Create a new preset

post

Authorizations

X-API-KEYstringRequired

Body

namestring · max: 100Required

descriptionstring · max: 500Optional

Responses

201

Preset created

application/json

post

/v1/presets

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

{
  "name": "text",
  "description": "text",
  "presets": {
    "language": "text",
    "location": "text",
    "tone": "seo_optimized",
    "pov": "first_person_singular",
    "article_type": "general",
    "target_length": "short",
    "include_ai_images": true,
    "ai_image_meta": {
      "image_model": "text",
      "image_style": "text",
      "image_count_body": 1,
      "use_brand_colors": true,
      "image_extra_prompt": "text"
    },
    "include_introduction": true,
    "include_conclusion": true,
    "include_faq": true,
    "include_meta_description": true,
    "extra_prompt": "text",
    "knowledge_sources": [
      1
    ]
  }
}

201

Preset created

{
  "id": 1,
  "name": "text",
  "description": "text",
  "target_content_type": "general",
  "created_at": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z",
  "presets": {
    "language": "text",
    "location": "text",
    "tone": "seo_optimized",
    "pov": "first_person_singular",
    "article_type": "general",
    "target_length": "short",
    "enable_pplx_fetch": true,
    "include_introduction": true,
    "include_conclusion": true,
    "include_faq": true,
    "include_featured_image": true,
    "include_meta_description": true,
    "include_youtube_videos": true,
    "position_key_takeaways": "none",
    "include_ai_images": true,
    "ai_image_meta": {
      "image_model": "text",
      "image_style": "text",
      "image_count_body": 1,
      "use_brand_colors": true,
      "image_extra_prompt": "text"
    },
    "extra_prompt": "text",
    "knowledge_sources": [
      1
    ]
  }
}

Get a preset by ID

get

Authorizations

X-API-KEYstringRequired

Path parameters

idintegerRequired

The preset ID

Responses

200

The preset with full settings

application/json

idintegerOptional

namestringOptional

descriptionstring · nullableOptional

target_content_typestring · enum · nullableOptionalPossible values:

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

get

/v1/presets/{id}

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

200

The preset with full settings

{
  "id": 1,
  "name": "text",
  "description": "text",
  "target_content_type": "general",
  "created_at": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z",
  "presets": {
    "language": "text",
    "location": "text",
    "tone": "seo_optimized",
    "pov": "first_person_singular",
    "article_type": "general",
    "target_length": "short",
    "enable_pplx_fetch": true,
    "include_introduction": true,
    "include_conclusion": true,
    "include_faq": true,
    "include_featured_image": true,
    "include_meta_description": true,
    "include_youtube_videos": true,
    "position_key_takeaways": "none",
    "include_ai_images": true,
    "ai_image_meta": {
      "image_model": "text",
      "image_style": "text",
      "image_count_body": 1,
      "use_brand_colors": true,
      "image_extra_prompt": "text"
    },
    "extra_prompt": "text",
    "knowledge_sources": [
      1
    ]
  }
}

Update a preset

put

Authorizations

X-API-KEYstringRequired

Path parameters

idintegerRequired

The preset ID

Body

namestring · max: 100Required

descriptionstring · max: 500Optional

Responses

200

Preset updated

application/json

idintegerOptional

namestringOptional

descriptionstring · nullableOptional

target_content_typestring · enum · nullableOptionalPossible values:

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

put

/v1/presets/{id}

PUT /v1/presets/{id} HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 495

{
  "name": "text",
  "description": "text",
  "presets": {
    "language": "text",
    "location": "text",
    "tone": "seo_optimized",
    "pov": "first_person_singular",
    "article_type": "general",
    "target_length": "short",
    "include_ai_images": true,
    "ai_image_meta": {
      "image_model": "text",
      "image_style": "text",
      "image_count_body": 1,
      "use_brand_colors": true,
      "image_extra_prompt": "text"
    },
    "include_introduction": true,
    "include_conclusion": true,
    "include_faq": true,
    "include_meta_description": true,
    "extra_prompt": "text",
    "knowledge_sources": [
      1
    ]
  }
}

200

Preset updated

{
  "id": 1,
  "name": "text",
  "description": "text",
  "target_content_type": "general",
  "created_at": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z",
  "presets": {
    "language": "text",
    "location": "text",
    "tone": "seo_optimized",
    "pov": "first_person_singular",
    "article_type": "general",
    "target_length": "short",
    "enable_pplx_fetch": true,
    "include_introduction": true,
    "include_conclusion": true,
    "include_faq": true,
    "include_featured_image": true,
    "include_meta_description": true,
    "include_youtube_videos": true,
    "position_key_takeaways": "none",
    "include_ai_images": true,
    "ai_image_meta": {
      "image_model": "text",
      "image_style": "text",
      "image_count_body": 1,
      "use_brand_colors": true,
      "image_extra_prompt": "text"
    },
    "extra_prompt": "text",
    "knowledge_sources": [
      1
    ]
  }
}

List knowledge sources

get

Returns a list of knowledge sources (RAG documents). Requires Power plan or higher.

Authorizations

X-API-KEYstringRequired

Query parameters

pageintegerOptional

Page number for pagination

Responses

200

A list of knowledge sources

application/json

idintegerOptional

namestringOptional

descriptionstring · nullableOptional

source_typestring · enumOptionalPossible values:

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

get

/v1/knowledge

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

200

A list of knowledge sources

[
  {
    "id": 1,
    "name": "text",
    "description": "text",
    "source_type": "text",
    "indexing": {
      "chunks_indexed": 1,
      "total_chunks": 1,
      "was_limited": true,
      "indexed_at": "2026-03-21T17:40:42.691Z"
    },
    "created_at": "2026-03-21T17:40:42.691Z",
    "updated_at": "2026-03-21T17:40:42.691Z"
  }
]

Delete a preset

delete

Authorizations

X-API-KEYstringRequired

Path parameters

idintegerRequired

The preset ID

Responses

204

Preset deleted

delete

/v1/presets/{id}

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

204

Preset deleted

No content

Create a text knowledge source

post

Create a knowledge source from text content. For file uploads, use POST /v1/knowledge/upload.

Authorizations

X-API-KEYstringRequired

Body

namestring · max: 200Required

descriptionstring · max: 500Optional

contentstring · max: 100000Required

The text content to index

Responses

201

Knowledge source created

application/json

post

/v1/knowledge

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

{
  "name": "text",
  "description": "text",
  "content": "text"
}

201

Knowledge source created

{
  "id": 1,
  "name": "text",
  "description": "text",
  "source_type": "text",
  "indexing": {
    "chunks_indexed": 1,
    "total_chunks": 1,
    "was_limited": true,
    "indexed_at": "2026-03-21T17:40:42.691Z"
  },
  "created_at": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z"
}

Request upload URL for file-based knowledge

post

Get a signed URL to upload a PDF or TXT file. After uploading, call POST /v1/knowledge/{id}/confirm to trigger processing. Maximum file size: 50MB.

Authorizations

X-API-KEYstringRequired

Body

namestring · max: 200Required

descriptionstring · max: 500Optional

filenamestringRequired

content_typestring · enumRequiredPossible values:

Responses

201

Upload URL generated

application/json

post

/v1/knowledge/upload

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

{
  "name": "text",
  "description": "text",
  "filename": "text",
  "content_type": "application/pdf"
}

201

Upload URL generated

{
  "knowledge_id": 1,
  "upload_url": "text",
  "expires_at": "2026-03-21T17:40:42.691Z"
}

List keyword clusters

get

Returns keyword clusters for content planning. Requires Power plan or higher.

Authorizations

X-API-KEYstringRequired

Query parameters

pageintegerOptional

sitestring · uuidOptional

Filter by site ID

in_planbooleanOptional

Filter by active clusters

Responses

200

A list of clusters

application/json

idstring · uuidOptional

site_idstring · uuidOptional

titlestringOptional

descriptionstring · nullableOptional

in_planbooleanOptional

Whether this cluster is active in content planning

pillar_pagestring · nullableOptional

URL of the pillar page for this cluster

total_keywordsintegerOptional

total_search_volumeintegerOptional

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

get

/v1/clusters

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

200

A list of clusters

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "site_id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "text",
    "description": "text",
    "in_plan": true,
    "pillar_page": "text",
    "total_keywords": 1,
    "total_search_volume": 1,
    "created_at": "2026-03-21T17:40:42.691Z",
    "updated_at": "2026-03-21T17:40:42.691Z"
  }
]

Get a cluster with keywords

get

Authorizations

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The cluster ID

Responses

200

Cluster with keywords

application/json

idstring · uuidOptional

site_idstring · uuidOptional

titlestringOptional

descriptionstring · nullableOptional

in_planbooleanOptional

Whether this cluster is active in content planning

pillar_pagestring · nullableOptional

URL of the pillar page for this cluster

total_keywordsintegerOptional

total_search_volumeintegerOptional

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

get

/v1/clusters/{id}

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

200

Cluster with keywords

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "in_plan": true,
  "pillar_page": "text",
  "total_keywords": 1,
  "total_search_volume": 1,
  "created_at": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z",
  "keywords": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "keyword": "text",
      "search_volume": 1,
      "keyword_difficulty": 1,
      "cpc": 1,
      "search_intent": "text",
      "article_id": "text"
    }
  ]
}

Activate a cluster

post

Mark a cluster as "In Plan" for content planning. Requires Power plan or higher.

Authorizations

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The cluster ID

Responses

200

Cluster activated

application/json

idstring · uuidOptional

site_idstring · uuidOptional

titlestringOptional

descriptionstring · nullableOptional

in_planbooleanOptional

Whether this cluster is active in content planning

pillar_pagestring · nullableOptional

URL of the pillar page for this cluster

total_keywordsintegerOptional

total_search_volumeintegerOptional

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

post

/v1/clusters/{id}/activate

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

200

Cluster activated

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "in_plan": true,
  "pillar_page": "text",
  "total_keywords": 1,
  "total_search_volume": 1,
  "created_at": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z"
}

Deactivate a cluster

post

Remove a cluster from "In Plan". Requires Power plan or higher.

Authorizations

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The cluster ID

Responses

200

Cluster deactivated

application/json

idstring · uuidOptional

site_idstring · uuidOptional

titlestringOptional

descriptionstring · nullableOptional

in_planbooleanOptional

Whether this cluster is active in content planning

pillar_pagestring · nullableOptional

URL of the pillar page for this cluster

total_keywordsintegerOptional

total_search_volumeintegerOptional

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

post

/v1/clusters/{id}/deactivate

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

200

Cluster deactivated

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "in_plan": true,
  "pillar_page": "text",
  "total_keywords": 1,
  "total_search_volume": 1,
  "created_at": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z"
}

List content planner items

get

Returns scheduled content items. Requires Power plan or higher.

Authorizations

X-API-KEYstringRequired

Query parameters

pageintegerOptional

sitestring · uuidOptional

statusstring · enumOptionalPossible values:

from_datestring · dateOptional

Filter items scheduled on or after this date

to_datestring · dateOptional

Filter items scheduled on or before this date

Responses

200

A list of planner items

application/json

Content planner item. Uses keyword_id as the unique identifier.

keyword_idstring · uuidOptional

The unique identifier for this planner item (also the keyword ID)

site_idstring · uuidOptional

cluster_idstring · uuidOptional

datestring · dateOptional

Scheduled date for content creation

statusstring · enumOptionalPossible values:

keywordstring · nullableOptional

The keyword text

cluster_titlestring · nullableOptional

Title of the parent cluster

metadataobject · nullableOptional

Additional metadata (may contain article_id after content is created)

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

get

/v1/planner

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

200

A list of planner items

[
  {
    "keyword_id": "123e4567-e89b-12d3-a456-426614174000",
    "site_id": "123e4567-e89b-12d3-a456-426614174000",
    "cluster_id": "123e4567-e89b-12d3-a456-426614174000",
    "date": "2026-03-21",
    "status": "scheduled",
    "keyword": "text",
    "cluster_title": "text",
    "metadata": {},
    "created_at": "2026-03-21T17:40:42.691Z",
    "updated_at": "2026-03-21T17:40:42.691Z"
  }
]

Create a planner item

post

Schedule a keyword for content creation. Each keyword can only be scheduled once.

Authorizations

X-API-KEYstringRequired

Body

site_idstring · uuidRequired

keyword_idstring · uuidRequired

The keyword to schedule (must exist in site_keywords)

cluster_idstring · uuidRequired

The cluster this keyword belongs to

datestring · dateRequired

Scheduled date for content creation

statusstring · enumOptionalDefault: scheduledPossible values:

Responses

201

Planner item created

application/json

409

Planner item already exists for this keyword

application/json

post

/v1/planner

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

{
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "keyword_id": "123e4567-e89b-12d3-a456-426614174000",
  "cluster_id": "123e4567-e89b-12d3-a456-426614174000",
  "date": "2026-03-21",
  "status": "scheduled"
}

{
  "keyword_id": "123e4567-e89b-12d3-a456-426614174000",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "cluster_id": "123e4567-e89b-12d3-a456-426614174000",
  "date": "2026-03-21",
  "status": "scheduled",
  "keyword": "text",
  "cluster_title": "text",
  "metadata": {},
  "created_at": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z"
}

Get a planner item

get

Get a single planner item by keyword_id. Requires Power plan or higher.

Authorizations

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The keyword_id of the planner item

Responses

200

The planner item

application/json

Content planner item. Uses keyword_id as the unique identifier.

keyword_idstring · uuidOptional

The unique identifier for this planner item (also the keyword ID)

site_idstring · uuidOptional

cluster_idstring · uuidOptional

datestring · dateOptional

Scheduled date for content creation

statusstring · enumOptionalPossible values:

keywordstring · nullableOptional

The keyword text

cluster_titlestring · nullableOptional

Title of the parent cluster

metadataobject · nullableOptional

Additional metadata (may contain article_id after content is created)

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

404

Planner item not found

application/json

get

/v1/planner/{id}

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

{
  "keyword_id": "123e4567-e89b-12d3-a456-426614174000",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "cluster_id": "123e4567-e89b-12d3-a456-426614174000",
  "date": "2026-03-21",
  "status": "scheduled",
  "keyword": "text",
  "cluster_title": "text",
  "metadata": {},
  "created_at": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z"
}

Update a planner item

put

Update the scheduled date or status of a planner item. Requires Power plan or higher.

Authorizations

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The keyword_id of the planner item

Body

datestring · dateOptional

New scheduled date

statusstring · enumOptional

New status

Possible values:

Responses

200

Planner item updated

application/json

Content planner item. Uses keyword_id as the unique identifier.

keyword_idstring · uuidOptional

The unique identifier for this planner item (also the keyword ID)

site_idstring · uuidOptional

cluster_idstring · uuidOptional

datestring · dateOptional

Scheduled date for content creation

statusstring · enumOptionalPossible values:

keywordstring · nullableOptional

The keyword text

cluster_titlestring · nullableOptional

Title of the parent cluster

metadataobject · nullableOptional

Additional metadata (may contain article_id after content is created)

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

400

Invalid status transition

application/json

put

/v1/planner/{id}

PUT /v1/planner/{id} HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 42

{
  "date": "2026-03-21",
  "status": "scheduled"
}

{
  "keyword_id": "123e4567-e89b-12d3-a456-426614174000",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "cluster_id": "123e4567-e89b-12d3-a456-426614174000",
  "date": "2026-03-21",
  "status": "scheduled",
  "keyword": "text",
  "cluster_title": "text",
  "metadata": {},
  "created_at": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z"
}

Delete a planner item

delete

Remove a scheduled item from the content planner. Cannot delete created/published items. Requires Power plan or higher.

Authorizations

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The keyword_id of the planner item

Responses

200

Planner item deleted

application/json

successbooleanOptional

400

Cannot delete created or published items

application/json

delete

/v1/planner/{id}

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

{
  "success": true
}

post

Generate a social media post from article content. Requires Power plan or higher. Uses your OpenAI API key for text generation, and optionally Replicate API key for image generation.

Authorizations

X-API-KEYstringRequired

Body

site_idstring · uuidRequired

article_idstring · uuid · nullableOptional

article_titlestringRequired

article_summarystringRequired

article_urlstring · uri · nullableOptional

platformstring · enumRequiredPossible values:

tonestring · enumOptionalDefault: engagingPossible values:

include_hashtagsbooleanOptionalDefault: true

max_hashtagsinteger · max: 30Optional

hook_typestring · enumOptionalPossible values:

generate_imagebooleanOptionalDefault: false

Responses

201

Social post generated

application/json

post

/v1/social

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

{
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "article_id": "123e4567-e89b-12d3-a456-426614174000",
  "article_title": "text",
  "article_summary": "text",
  "article_url": "https://example.com",
  "platform": "twitter",
  "tone": "engaging",
  "include_hashtags": true,
  "max_hashtags": 1,
  "hook_type": "curiosity",
  "generate_image": false
}

201

Social post generated

{
  "content": "text",
  "hashtags": [
    "text"
  ],
  "image_prompt": "text",
  "image_url": "text",
  "platform": "text",
  "character_count": 1,
  "hook": "text",
  "metadata": {
    "tokens_used": 1,
    "model": "text",
    "generated_at": "2026-03-21T17:40:42.691Z",
    "brand_context_used": true
  }
}

get

Returns all supported social platforms with their character limits and best practices.

Authorizations

X-API-KEYstringRequired

Responses

200

List of platforms

application/json

idstringOptional

labelstringOptional

max_charactersintegerOptional

hashtags_supportedbooleanOptional

max_hashtagsintegerOptional

get

/v1/social/platforms

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

200

List of platforms

[
  {
    "id": "text",
    "label": "text",
    "max_characters": 1,
    "hashtags_supported": true,
    "max_hashtags": 1
  }
]

List Link Engine sites

get

Returns sites with Link Engine configuration. Requires Power plan or higher.

Authorizations

X-API-KEYstringRequired

Query parameters

pageintegerOptional

searchstringOptional

Search by domain

categorystring · uuidOptional

statusstring · enumOptionalPossible values:

Responses

200

List of Link Engine sites

application/json

get

/v1/links

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

200

List of Link Engine sites

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "domain": "text",
      "link_engine_status": "active",
      "link_engine_url_count": 1,
      "link_engine_last_indexed_at": "2026-03-21T17:40:42.691Z",
      "link_engine_error": "text",
      "category_id": "123e4567-e89b-12d3-a456-426614174000",
      "category_name": "text",
      "has_link_config": true,
      "created_at": "2026-03-21T17:40:42.691Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 1,
    "total": 1,
    "total_pages": 1
  }
}

Get Link Engine statistics

get

Authorizations

X-API-KEYstringRequired

Responses

200

Link Engine stats

application/json

total_sitesintegerOptional

active_sitesintegerOptional

paused_sitesintegerOptional

indexing_sitesintegerOptional

error_sitesintegerOptional

total_urlsintegerOptional

get

/v1/links/stats

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

200

Link Engine stats

{
  "total_sites": 1,
  "active_sites": 1,
  "paused_sites": 1,
  "indexing_sites": 1,
  "error_sites": 1,
  "total_urls": 1
}

List link categories

get

Authorizations

X-API-KEYstringRequired

Responses

200

List of categories

application/json

idstring · uuidOptional

namestringOptional

slugstringOptional

descriptionstring · nullableOptional

colorstringOptional

site_countintegerOptional

created_atstring · date-timeOptional

get

/v1/links/categories

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

200

List of categories

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "slug": "text",
    "description": "text",
    "color": "text",
    "site_count": 1,
    "created_at": "2026-03-21T17:40:42.691Z"
  }
]

Create a link category

post

Authorizations

X-API-KEYstringRequired

Body

namestring · max: 50Required

descriptionstring · max: 200Optional

colorstringOptionalDefault: #6366f1Pattern: ^#[0-9A-Fa-f]{6}$

Responses

201

Category created

application/json

post

/v1/links/categories

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

{
  "name": "text",
  "description": "text",
  "color": "#6366f1"
}

201

Category created

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "slug": "text",
  "description": "text",
  "color": "text",
  "site_count": 1,
  "created_at": "2026-03-21T17:40:42.691Z"
}

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

modelsstring[]Required

image_modelsstring[]Required

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

string[]Optional

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

Returns all available image generation models. Models are grouped by provider:

OpenAI models (require OpenAI API key):

gpt-image-1: GPT Image 1, photorealistic quality. Sizes: 1024x1024, 1536x1024, 1024x1536

Replicate models (require Replicate API key):

black-forest-labs/flux-1.1-pro-ultra: Flux 1.1 Pro Ultra, highest quality Flux model
black-forest-labs/flux-1.1-pro: Flux 1.1 Pro, high quality with custom dimensions
black-forest-labs/flux-dev: Flux Dev, fast iteration
black-forest-labs/flux-pro: Flux Pro, balanced quality and speed
black-forest-labs/flux-schnell: Flux Schnell, fastest Flux model
stability-ai/stable-diffusion-3: Stable Diffusion 3
replicate:nano-banana-pro: Nano Banana Pro, supports 1K/2K/4K resolution output
replicate:imagen-4: Google Imagen 4 via Replicate

Google models (require Google AI API key):

imagen-4.0-generate-001: Google Imagen 4, native Google API

Authorizations

X-API-KEYstringRequired

Responses

200

A list of image model names

application/json

string[]OptionalExample:

["gpt-image-1","black-forest-labs/flux-1.1-pro-ultra","black-forest-labs/flux-1.1-pro","black-forest-labs/flux-dev","black-forest-labs/flux-pro","black-forest-labs/flux-schnell","stability-ai/stable-diffusion-3","replicate:nano-banana-pro","replicate:imagen-4","imagen-4.0-generate-001"]

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

[
  "gpt-image-1",
  "black-forest-labs/flux-1.1-pro-ultra",
  "black-forest-labs/flux-1.1-pro",
  "black-forest-labs/flux-dev",
  "black-forest-labs/flux-pro",
  "black-forest-labs/flux-schnell",
  "stability-ai/stable-diffusion-3",
  "replicate:nano-banana-pro",
  "replicate:imagen-4",
  "imagen-4.0-generate-001"
]

Get available languages

get

Authorizations

X-API-KEYstringRequired

Responses

200

A list of supported languages

application/json

namestringRequired

codestringRequired

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

namestringRequired

codestringRequired

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

idstringRequired

urlstringRequired

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 the full list. OpenAI models use the size setting. Replicate/Google models use the aspect_ratio setting.

Example: gpt-image-1

promptstring · max: 1000Required

The prompt to use for image generation

Responses

200

Successfully generated image

application/json

idstringOptional

urlstringOptional

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: 111

{
  "model": "gpt-image-1",
  "prompt": "text",
  "settings": {
    "size": "1536x1024",
    "aspect_ratio": "16:9",
    "resolution": "1K"
  }
}

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.

sitestring · uuid · nullableOptional

Filter by site/brand ID. Use GET /v1/sites to get available site IDs.

Responses

200

A list of articles

application/json

idstringOptional

is_draftbooleanOptional

Whether the article is a draft

statusstring · enumOptionalPossible values:

titlestring · nullableOptional

It is null if the article is not generated yet.

contentstring · nullableOptional

It is null if the article is not generated yet.

snippetstring · nullableOptional

project_idstring · nullableOptional

It is null if the article is not part of a project.

site_idstring · uuid · nullableOptional

The site/brand ID associated with this article. Null if no brand context.

meta_descriptionstring · nullableOptional

content_typestring · enumOptionalPossible values:

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

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",
    "site_id": "123e4567-e89b-12d3-a456-426614174000",
    "meta_description": "text",
    "featured_images": [
      {
        "url": "text",
        "alt": "text"
      }
    ],
    "content_type": "article",
    "settings": {
      "model": "text",
      "target_keyword": "text",
      "language": "text",
      "region": "text"
    },
    "created_at": "2026-03-21T17:40:42.691Z",
    "updated_at": "2026-03-21T17:40:42.691Z"
  }
]

Create a new article

post

Create content using different templates:

article (default): Full-featured articles with support for listicles, reviews, how-tos. Use settings.article_type to specify.
local_news: Location-focused news articles. Simpler settings, uses local_news_settings.
recipe: Structured recipe content with ingredients, instructions. Uses recipe_settings.

Authorizations

X-API-KEYstringRequired

Body

target_keywordstringRequired

The target keyword for the content.

templatestring · enumOptional

The content template to use:

article: General articles with full settings (listicle, review, howto, general)
local_news: Location-focused news content
recipe: Structured recipe with ingredients and instructions

Default: articlePossible values:

site_idstring · uuid · nullableOptional

modelstringOptional

The AI model to use.

Default: gpt-4o-mini

settings_presetnumber · nullableOptional

Preset ID (only for template=article).

use_serpbooleanOptional

When true, fetches top SERP competitors before generation and uses their content as context to write a more competitive article. Requires a Power plan or higher.

Default: false

is_draftbooleanOptional

Whether to save as draft (won't generate immediately)

Default: false

Responses

200

Content created successfully

application/json

idstringOptional

is_draftbooleanOptional

Whether the article is a draft

statusstring · enumOptionalPossible values:

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: 1000

{
  "target_keyword": "text",
  "template": "article",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "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": "gpt-image-1",
      "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"
    }
  },
  "local_news_settings": {
    "target_audience": "text",
    "extra_prompt": "text"
  },
  "recipe_settings": {
    "recipe_template": "modern"
  },
  "use_serp": false,
  "is_draft": false
}

200

Content 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

idstringOptional

is_draftbooleanOptional

Whether the article is a draft

statusstring · enumOptionalPossible values:

titlestring · nullableOptional

It is null if the article is not generated yet.

contentstring · nullableOptional

It is null if the article is not generated yet.

snippetstring · nullableOptional

project_idstring · nullableOptional

It is null if the article is not part of a project.

site_idstring · uuid · nullableOptional

The site/brand ID associated with this article. Null if no brand context.

meta_descriptionstring · nullableOptional

content_typestring · enumOptionalPossible values:

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

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",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "meta_description": "text",
  "featured_images": [
    {
      "url": "text",
      "alt": "text"
    }
  ],
  "content_type": "article",
  "settings": {
    "model": "text",
    "target_keyword": "text",
    "language": "text",
    "region": "text"
  },
  "created_at": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z"
}

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

idstringOptional

is_draftbooleanOptional

Whether the article is a draft

statusstring · enumOptionalPossible values:

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

idstringOptional

namestringOptional

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

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": "2026-03-21T17:40:42.691Z",
    "updated_at": "2026-03-21T17:40:42.691Z"
  }
]

Create a new project

post

Authorizations

X-API-KEYstringRequired

Body

project_namestring · max: 100Required

Name of the project

site_idstring · uuid · nullableOptional

Optional site/brand ID. When provided, enables Brand Voice, site context, target audience, and Link Engine for all articles in the project. Use GET /v1/sites to list available sites.

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

idstringOptional

namestringOptional

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

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: 810

{
  "project_name": "text",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "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": "gpt-image-1",
      "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": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z"
}

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

idstringOptional

namestringOptional

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

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": "2026-03-21T17:40:42.691Z",
  "updated_at": "2026-03-21T17:40:42.691Z"
}

PreviousCustom Builds NextMetadata

Last updated 1 month ago

Was this helpful?

hashtagGet all metadata

hashtagGet available models

hashtagGet available image models

hashtagGet available languages

hashtagGet available regions

hashtagFetch list of generated images

hashtagCreate an image

hashtagFetch list of articles

hashtagCreate a new article

hashtagGet an article by ID

hashtagGet the current status of an article

hashtagGet content grade for an article

hashtagTrigger grading for an article

hashtagGet SERP analysis data for an article

hashtagFetch SERP data for an article

hashtagGet AI optimization suggestions

hashtagFetch list of projects

hashtagCreate a new project

hashtagGet a project by ID

hashtagExport project articles

hashtagList all sites/brands

hashtagGet a site by ID

hashtagGet all brand information for a site

hashtagList all presets

hashtagCreate a new preset

hashtagGet a preset by ID

hashtagUpdate a preset

hashtagList knowledge sources

hashtagDelete a preset

hashtagCreate a text knowledge source

hashtagRequest upload URL for file-based knowledge

hashtagList keyword clusters

hashtagGet a cluster with keywords

hashtagActivate a cluster

hashtagDeactivate a cluster

hashtagList content planner items

hashtagCreate a planner item

hashtagGet a planner item

hashtagUpdate a planner item

hashtagDelete a planner item

hashtagGenerate a social media post

hashtagGet supported social platforms

hashtagList Link Engine sites

hashtagGet Link Engine statistics

hashtagList link categories

hashtagCreate a link category

hashtagAuthentication

hashtagRate Limiting

hashtagError Handling

hashtagGet all metadata

hashtagGet available models

hashtagGet available image models

hashtagGet available languages

hashtagGet available regions

hashtagFetch list of generated images

hashtagCreate an image

hashtagFetch list of articles

hashtagCreate a new article

hashtagGet an article by ID

hashtagGet the current status of an article

hashtagFetch list of projects

hashtagCreate a new project

hashtagGet a project by ID

Get all metadata

Get available models

Get available image models

Get available languages

Get available regions

Fetch list of generated images

Create an image

Fetch list of articles

Create a new article

Get an article by ID

Get the current status of an article

Get content grade for an article

Trigger grading for an article

Get SERP analysis data for an article

Fetch SERP data for an article

Get AI optimization suggestions

Fetch list of projects

Create a new project

Get a project by ID

Export project articles

List all sites/brands

Get a site by ID

Get all brand information for a site

List all presets

Create a new preset

Get a preset by ID

Update a preset

List knowledge sources

Delete a preset

Create a text knowledge source

Request upload URL for file-based knowledge

List keyword clusters

Get a cluster with keywords

Activate a cluster

Deactivate a cluster

List content planner items

Create a planner item

Get a planner item

Update a planner item

Delete a planner item

Generate a social media post

Get supported social platforms

List Link Engine sites

Get Link Engine statistics

List link categories

Create a link category

Authentication

Rate Limiting

Error Handling

Get all metadata

Get available models

Get available image models

Get available languages

Get available regions

Fetch list of generated images

Create an image

Fetch list of articles

Create a new article

Get an article by ID

Get the current status of an article

Fetch list of projects

Create a new project

Get a project by ID