Contents

Create and manage articles

Fetch list of articles

get

Authorizations

ApiKeyAuth

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

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",
    "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-22T03:34:22.649Z",
    "updated_at": "2026-03-22T03:34:22.649Z"
  }
]

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

ApiKeyAuth

X-API-KEYstringRequired

Body

application/json

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

HTTPcURLJavaScriptPython

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

Import article from URL

post

Import an existing article by URL. Scrapes the page and creates a Cuppa article.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Body

application/json

urlstringRequired

URL to import

languagestringOptional

Language code

Default: en

site_idstring · uuidOptional

Site to associate with

Responses

201

Article imported

application/json

post

/v1/contents/import

HTTPcURLJavaScriptPython

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

{
  "url": "text",
  "language": "en",
  "site_id": "123e4567-e89b-12d3-a456-426614174000"
}

201

Article imported

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

Get an article by ID

get

Authorizations

ApiKeyAuth

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}

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",
  "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-22T03:34:22.649Z",
  "updated_at": "2026-03-22T03:34:22.649Z"
}

Update an article

patch

Update title, content, meta description, or target keyword of an existing article. At least one field is required.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstringRequired

The article ID

Body

application/json

titlestringOptional

Article title

contentstringOptional

HTML content

meta_descriptionstringOptional

SEO meta description

target_keywordstringOptional

Target keyword

Responses

200

The updated article

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

patch

/v1/contents/{id}

HTTPcURLJavaScriptPython

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

{
  "title": "text",
  "content": "text",
  "meta_description": "text",
  "target_keyword": "text"
}

200

The updated article

{
  "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-22T03:34:22.649Z",
  "updated_at": "2026-03-22T03:34:22.649Z"
}

Get the current status of an article

get

Authorizations

ApiKeyAuth

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

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

Get content grade for an article

get

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

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstringRequired

The article ID

Responses

200

Article grade

application/json

existsbooleanOptional

get

/v1/contents/{id}/grade

HTTPcURLJavaScriptPython

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-22T03:34:22.649Z",
    "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

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstringRequired

The article ID

Responses

200

Article graded successfully

application/json

existsbooleanOptional

post

/v1/contents/{id}/grade

HTTPcURLJavaScriptPython

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-22T03:34:22.649Z",
    "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

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstringRequired

The article ID

Responses

200

SERP analysis data

application/json

statusstring · enumOptionalPossible values:

get

/v1/contents/{id}/serp

HTTPcURLJavaScriptPython

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-22T03:34:22.649Z",
    "updated_at": "2026-03-22T03:34:22.649Z"
  },
  "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

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstringRequired

The article ID

Body

application/json

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

HTTPcURLJavaScriptPython

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

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstringRequired

The article ID

Body

application/json

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

HTTPcURLJavaScriptPython

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

Publish article to CMS platform

post

Push an article to an external CMS (Ghost, Webflow, Contentful, Sanity, Airtable). The integration must be configured in team settings first. Requires Power plan or higher.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstringRequired

The article ID

Body

application/json

platformstring · enumRequiredPossible values:

Responses

200

Article published

application/json

successbooleanOptional

platformstringOptional

external_idstring · nullableOptional

external_urlstring · nullableOptional

errorstring · nullableOptional

post

/v1/contents/{id}/publish

HTTPcURLJavaScriptPython

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

{
  "platform": "ghost",
  "options": {
    "status": "publish",
    "categories": [
      "text"
    ],
    "tags": [
      "text"
    ],
    "collection_id": "text"
  }
}

200

Article published

{
  "success": true,
  "platform": "text",
  "external_id": "text",
  "external_url": "text",
  "error": "text"
}