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

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-02-04T17:21:46.957Z",
    "updated_at": "2026-02-04T17:21:46.957Z"
  }
]

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. Enables Brand Voice, site context, and Link Engine.

modelstringOptional

The AI model to use.

Default: gpt-4o-mini

settings_presetnumber · nullableOptional

Preset ID (only for template=article).

is_draftbooleanOptional

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

Default: false

Responses

200

Content created successfully

application/json

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

{
  "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": "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"
    }
  },
  "local_news_settings": {
    "target_audience": "text",
    "extra_prompt": "text"
  },
  "recipe_settings": {
    "recipe_template": "modern"
  },
  "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

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstringRequired

The ID of the article

Responses

200

The article object

application/json

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-02-04T17:21:46.957Z",
  "updated_at": "2026-02-04T17:21:46.957Z"
}

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

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

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-02-04T17:21:46.957Z",
    "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

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-02-04T17:21:46.957Z",
    "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

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-02-04T17:21:46.957Z",
    "updated_at": "2026-02-04T17:21:46.957Z"
  },
  "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

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

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 (WordPress, 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

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

{
  "platform": "wordpress",
  "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"
}