# API reference

{% hint style="info" %}
Available on [Business](broken://pages/didKfuWnEDt9OS6YPnsw) and above.
{% endhint %}

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

## GET /v1/meta

> Get all metadata

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Metadata","description":"API metadata and available options"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/meta":{"get":{"summary":"Get all metadata","responses":{"200":{"description":"Metadata object","content":{"application/json":{"schema":{"type":"object","properties":{"languages":{"type":"array","items":{"type":"object","required":["name","code"],"properties":{"name":{"type":"string"},"code":{"type":"string"}}}},"regions":{"type":"array","items":{"type":"object","required":["name","code"],"properties":{"name":{"type":"string"},"code":{"type":"string"}}}},"models":{"type":"array","items":{"type":"string"}},"image_models":{"type":"array","items":{"type":"string"}}},"required":["languages","regions","models","image_models"]}}}}},"tags":["Metadata"]}}}}
```

## GET /v1/meta/models

> Get available models

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Metadata","description":"API metadata and available options"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/meta/models":{"get":{"summary":"Get available models","responses":{"200":{"description":"A list of model names","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}}},"tags":["Metadata"]}}}}
```

## Get available image models

> Returns all available image generation models. Models are grouped by provider:\
> \
> \*\*OpenAI models\*\* (require OpenAI API key):\
> \- \`gpt-image-2\`: GPT Image 2, latest state-of-the-art OpenAI image model. Sizes: 1024x1024, 1536x1024, 1024x1536\
> \- \`gpt-image-1.5\`: GPT Image 1.5, fast and high quality. Sizes: 1024x1024, 1536x1024, 1024x1536\
> \- \`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<br>

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Metadata","description":"API metadata and available options"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/meta/image_models":{"get":{"summary":"Get available image models","description":"Returns all available image generation models. Models are grouped by provider:\n\n**OpenAI models** (require OpenAI API key):\n- `gpt-image-2`: GPT Image 2, latest state-of-the-art OpenAI image model. Sizes: 1024x1024, 1536x1024, 1024x1536\n- `gpt-image-1.5`: GPT Image 1.5, fast and high quality. Sizes: 1024x1024, 1536x1024, 1024x1536\n- `gpt-image-1`: GPT Image 1, photorealistic quality. Sizes: 1024x1024, 1536x1024, 1024x1536\n\n**Replicate models** (require Replicate API key):\n- `black-forest-labs/flux-1.1-pro-ultra`: Flux 1.1 Pro Ultra, highest quality Flux model\n- `black-forest-labs/flux-1.1-pro`: Flux 1.1 Pro, high quality with custom dimensions\n- `black-forest-labs/flux-dev`: Flux Dev, fast iteration\n- `black-forest-labs/flux-pro`: Flux Pro, balanced quality and speed\n- `black-forest-labs/flux-schnell`: Flux Schnell, fastest Flux model\n- `stability-ai/stable-diffusion-3`: Stable Diffusion 3\n- `replicate:nano-banana-pro`: Nano Banana Pro, supports 1K/2K/4K resolution output\n- `replicate:imagen-4`: Google Imagen 4 via Replicate\n\n**Google models** (require Google AI API key):\n- `imagen-4.0-generate-001`: Google Imagen 4, native Google API\n","responses":{"200":{"description":"A list of image model names","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}}},"tags":["Metadata"]}}}}
```

## GET /v1/meta/languages

> Get available languages

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Metadata","description":"API metadata and available options"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/meta/languages":{"get":{"summary":"Get available languages","responses":{"200":{"description":"A list of supported languages","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["name","code"],"properties":{"name":{"type":"string"},"code":{"type":"string"}}}}}}}},"tags":["Metadata"]}}}}
```

## GET /v1/meta/regions

> Get available regions

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Metadata","description":"API metadata and available options"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/meta/regions":{"get":{"summary":"Get available regions","responses":{"200":{"description":"A list of supported regions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["name","code"],"properties":{"name":{"type":"string"},"code":{"type":"string"}}}}}}}},"tags":["Metadata"]}}}}
```

## GET /v1/images

> Fetch list of generated images

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Images","description":"AI image generation"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/images":{"get":{"summary":"Fetch list of generated images","parameters":[{"in":"query","name":"limit","schema":{"type":"integer","maximum":50},"description":"Maximum number of images to return (max 50, default 20)"}],"responses":{"200":{"description":"A list of generated images","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","url"],"properties":{"id":{"type":"string"},"url":{"type":"string"}}}}}}}},"tags":["Images"]}}}}
```

## POST /v1/images

> Create an image

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Images","description":"AI image generation"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/images":{"post":{"summary":"Create an image","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","prompt"],"properties":{"model":{"type":"string","description":"The model to use for image generation. Use the `/v1/meta/image_models` endpoint to get the full list.\nOpenAI models use the `size` setting. Replicate/Google models use the `aspect_ratio` setting.\n"},"prompt":{"type":"string","maxLength":1000,"description":"The prompt to use for image generation"},"settings":{"type":"object","description":"Image generation settings. Use `size` for OpenAI models, `aspect_ratio` for Replicate/Google models.","properties":{"size":{"type":"string","enum":["1024x1024","1536x1024","1024x1536"],"default":"1536x1024","description":"Pixel size of the image. Valid for OpenAI models (gpt-image-1, gpt-image-1.5, gpt-image-2) only.\n1024x1024 (square), 1536x1024 (landscape), 1024x1536 (portrait).\n"},"aspect_ratio":{"type":"string","enum":["1:1","16:9","9:16","4:3","3:4","3:2","2:3","5:4","4:5","21:9","9:21"],"default":"16:9","description":"Aspect ratio of the image. Valid for Replicate and Google models.\nNot all ratios are supported by all models. Common options: 16:9 (landscape), 9:16 (portrait/stories), 1:1 (square), 4:3 (standard), 3:2 (classic).\n"},"resolution":{"type":"string","enum":["1K","2K","4K"],"description":"Output resolution. Only valid for `replicate:nano-banana-pro`.\n1K: Fast, good for previews. 2K: Balanced (default). 4K: Highest quality, slower.\n"}}}}}}}},"responses":{"200":{"description":"Successfully generated image","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"}}}}}}},"tags":["Images"]}}}}
```

## GET /v1/contents

> Fetch list of articles

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Contents","description":"Create and manage articles"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Content":{"type":"object","properties":{"id":{"type":"string"},"is_draft":{"type":"boolean","description":"Whether the article is a draft"},"status":{"$ref":"#/components/schemas/TaskStatus"},"title":{"type":"string","nullable":true,"description":"It is null if the article is not generated yet."},"content":{"type":"string","nullable":true,"description":"It is null if the article is not generated yet."},"snippet":{"type":"string","nullable":true},"project_id":{"type":"string","nullable":true,"description":"It is null if the article is not part of a project."},"site_id":{"type":"string","format":"uuid","nullable":true,"description":"The site/brand ID associated with this article. Null if no brand context."},"meta_description":{"type":"string","nullable":true},"featured_images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"alt":{"type":"string","nullable":true}}}},"content_type":{"type":"string","enum":["article"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"target_keyword":{"type":"string"},"language":{"type":"string"},"region":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}},"paths":{"/v1/contents":{"get":{"summary":"Fetch list of articles","parameters":[{"in":"query","name":"page","schema":{"type":"integer","nullable":true},"description":"Page number for pagination"},{"in":"query","name":"lang","schema":{"type":"string","nullable":true},"description":"Filter by language code"},{"in":"query","name":"project","schema":{"type":"string","nullable":true},"description":"Filter by project ID. If not provided, it will return the articles not part of any project. Use `all` to get all articles."},{"in":"query","name":"site","schema":{"type":"string","format":"uuid","nullable":true},"description":"Filter by site/brand ID. Use `GET /v1/sites` to get available site IDs."}],"responses":{"200":{"description":"A list of articles","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Content"}}}}}},"tags":["Contents"]}}}}
```

## Create a new article

> 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\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Contents","description":"Create and manage articles"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"ContentSettings":{"type":"object","required":["language","region"],"properties":{"language":{"type":"string","description":"The language of the article."},"region":{"type":"string","description":"The region of the article."},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"],"default":"seo_optimized","description":"The tone of the article."},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"],"default":"first_person_plural","description":"The point of view of the article."},"article_type":{"type":"string","enum":["general","listicle","review","howto","recipe"],"default":"general","description":"The type of the article."},"fetch_perplexity":{"type":"boolean","default":false,"description":"Whether to use Perplexity for fetching real-time research data. It requires a Perplexity API key."},"include_introduction":{"type":"boolean","default":true,"description":"Whether to include an introduction section in the article."},"include_conclusion":{"type":"boolean","default":true,"description":"Whether to include a conclusion section in the article."},"include_yt_suggestions":{"type":"boolean","default":false,"description":"Whether to include YouTube suggestions in the article."},"generate_faqs":{"type":"boolean","default":false,"description":"Whether to generate a FAQ section in the article."},"generate_meta_description":{"type":"boolean","default":false,"description":"Whether to generate a meta description for the article."},"key_takeaways_position":{"type":"string","default":"none","enum":["top","bottom","none"],"description":"The position of the key takeaways section in the article. Use `none` to disable it."},"include_stock_images":{"type":"boolean","default":false,"description":"Whether to include stock featured images in the article."},"generate_images":{"type":"boolean","default":false,"description":"Whether to generate AI images for the article. Use the `image_settings` object to configure image generation."},"image_settings":{"type":"object","properties":{"model":{"type":"string","default":"gpt-image-1","description":"The image model to use for generation. Use the `/v1/meta/image_models` endpoint to get available image models."},"max_body_images_count":{"type":"integer","minimum":0,"maximum":7,"description":"The maximum number of images to generate in the body. Use `0` to disable body images."},"style_preset":{"type":"string","enum":["vintage","professional","photorealistic","infographic","minimalist_art","comic","watercolor_painting","abstract_art","pop_art","model_3d","line_art"],"nullable":true,"default":"photorealistic","description":"The style preset for the images. Use `custom_style` if you prefer a custom style instead."},"custom_style":{"type":"object","required":["name","description"],"properties":{"name":{"type":"string","description":"The name of the custom style."},"description":{"type":"string","description":"The description of the custom style. This should be a short but detailed description of the style you want to apply to the images."}},"description":"The custom style for the images."}}},"advanced_settings":{"type":"object","properties":{"title_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the title."},"introduction_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the introduction."},"section_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the sections."},"meta_description_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the meta description."}}}}},"ContentStatusResponse":{"type":"object","properties":{"id":{"type":"string"},"is_draft":{"type":"boolean","description":"Whether the article is a draft"},"status":{"$ref":"#/components/schemas/TaskStatus"},"status_extra":{"type":"object","properties":{"error":{"type":"string","nullable":true,"description":"Error message if status is failed"}}}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}},"paths":{"/v1/contents":{"post":{"summary":"Create a new article","description":"Create content using different templates:\n- **article** (default): Full-featured articles with support for listicles, reviews, how-tos. Use `settings.article_type` to specify.\n- **local_news**: Location-focused news articles. Simpler settings, uses `local_news_settings`.\n- **recipe**: Structured recipe content with ingredients, instructions. Uses `recipe_settings`.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target_keyword"],"properties":{"target_keyword":{"type":"string","description":"The target keyword for the content."},"template":{"type":"string","enum":["article","local_news","recipe"],"default":"article","description":"The content template to use:\n- `article`: General articles with full settings (listicle, review, howto, general)\n- `local_news`: Location-focused news content\n- `recipe`: Structured recipe with ingredients and instructions\n"},"site_id":{"type":"string","format":"uuid","nullable":true,"description":"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."},"model":{"type":"string","description":"The AI model to use.","default":"gpt-4o-mini"},"outline":{"type":"array","description":"Optional outline (only for template=article).","items":{"oneOf":[{"type":"object","required":["type","level","title"],"properties":{"type":{"type":"string","enum":["heading"]},"level":{"type":"integer","enum":[2,3,4]},"title":{"type":"string"}}},{"type":"object","required":["type","code"],"properties":{"type":{"type":"string","enum":["custom_code"]},"name":{"type":"string","nullable":true},"code":{"type":"string"}}},{"type":"object","required":["type","code"],"properties":{"type":{"type":"string","enum":["shortcode"]},"name":{"type":"string","nullable":true},"code":{"type":"string"}}}]}},"settings_preset":{"type":"number","description":"Preset ID (only for template=article).","nullable":true},"settings":{"$ref":"#/components/schemas/ContentSettings","description":"Article settings (only for template=article)."},"local_news_settings":{"type":"object","description":"Settings for template=local_news.","properties":{"target_audience":{"type":"string","maxLength":500,"description":"Target audience for the local news article."},"extra_prompt":{"type":"string","maxLength":50000,"description":"Additional AI instructions."}}},"recipe_settings":{"type":"object","description":"Settings for template=recipe.","properties":{"recipe_template":{"type":"string","enum":["original","card","minimal","modern","elegant","magazine","vintage","compact"],"default":"modern","description":"Display template for the recipe."}}},"use_serp":{"type":"boolean","description":"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_draft":{"type":"boolean","description":"Whether to save as draft (won't generate immediately)","default":false}}}}}},"responses":{"200":{"description":"Content created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentStatusResponse"}}}}},"tags":["Contents"]}}}}
```

## GET /v1/contents/{id}

> Get an article by ID

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Contents","description":"Create and manage articles"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Content":{"type":"object","properties":{"id":{"type":"string"},"is_draft":{"type":"boolean","description":"Whether the article is a draft"},"status":{"$ref":"#/components/schemas/TaskStatus"},"title":{"type":"string","nullable":true,"description":"It is null if the article is not generated yet."},"content":{"type":"string","nullable":true,"description":"It is null if the article is not generated yet."},"snippet":{"type":"string","nullable":true},"project_id":{"type":"string","nullable":true,"description":"It is null if the article is not part of a project."},"site_id":{"type":"string","format":"uuid","nullable":true,"description":"The site/brand ID associated with this article. Null if no brand context."},"meta_description":{"type":"string","nullable":true},"featured_images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"alt":{"type":"string","nullable":true}}}},"content_type":{"type":"string","enum":["article"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"target_keyword":{"type":"string"},"language":{"type":"string"},"region":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}},"paths":{"/v1/contents/{id}":{"get":{"summary":"Get an article by ID","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The ID of the article"}],"responses":{"200":{"description":"The article object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Content"}}}}},"tags":["Contents"]}}}}
```

## GET /v1/contents/{id}/status

> Get the current status of an article

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Contents","description":"Create and manage articles"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"ContentStatusResponse":{"type":"object","properties":{"id":{"type":"string"},"is_draft":{"type":"boolean","description":"Whether the article is a draft"},"status":{"$ref":"#/components/schemas/TaskStatus"},"status_extra":{"type":"object","properties":{"error":{"type":"string","nullable":true,"description":"Error message if status is failed"}}}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}},"paths":{"/v1/contents/{id}/status":{"get":{"summary":"Get the current status of an article","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The ID of the article"}],"responses":{"200":{"description":"The status of the article","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentStatusResponse"}}}}},"tags":["Contents"]}}}}
```

## Get content grade for an article

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Contents","description":"Create and manage articles"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"ContentGrade":{"type":"object","description":"Content grade with SEO, readability, and SERP optimization scores","properties":{"overall_score":{"type":"integer","minimum":0,"maximum":100,"description":"Weighted average of all category scores"},"seo_score":{"type":"integer","minimum":0,"maximum":100},"readability_score":{"type":"integer","minimum":0,"maximum":100},"slop_score":{"type":"integer","minimum":0,"maximum":100,"description":"AI writing quality score (higher = less generic AI patterns)"},"ai_search_score":{"type":"integer","minimum":0,"maximum":100,"description":"AI search optimization (E-E-A-T signals, direct answers, etc.)"},"structure_score":{"type":"integer","minimum":0,"maximum":100},"technical_score":{"type":"integer","minimum":0,"maximum":100},"word_count":{"type":"integer","nullable":true},"target_keyword":{"type":"string","nullable":true},"graded_at":{"type":"string","format":"date-time"},"grader_version":{"type":"string"},"has_serp_data":{"type":"boolean","description":"Whether SERP optimization analysis is included"},"serp_score":{"type":"object","nullable":true,"description":"SERP optimization scores (only present if has_serp_data is true)","properties":{"overall":{"type":"number"},"term_coverage":{"type":"number","description":"Coverage of competitor terms in article"},"intent_alignment":{"type":"number","description":"How well content matches search intent"},"structure_match":{"type":"number","description":"Similarity to top-ranking content structure"},"paa_coverage":{"type":"number","description":"Coverage of People Also Ask questions"}}}}}}},"paths":{"/v1/contents/{id}/grade":{"get":{"summary":"Get content grade for an article","description":"Returns the content grade and SERP optimization scores for an article.\nRequires Power plan or higher.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The article ID"}],"responses":{"200":{"description":"Article grade","content":{"application/json":{"schema":{"type":"object","properties":{"grade":{"$ref":"#/components/schemas/ContentGrade"},"exists":{"type":"boolean"}}}}}}},"tags":["Contents"]}}}}
```

## Trigger grading for an article

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Contents","description":"Create and manage articles"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"ContentGrade":{"type":"object","description":"Content grade with SEO, readability, and SERP optimization scores","properties":{"overall_score":{"type":"integer","minimum":0,"maximum":100,"description":"Weighted average of all category scores"},"seo_score":{"type":"integer","minimum":0,"maximum":100},"readability_score":{"type":"integer","minimum":0,"maximum":100},"slop_score":{"type":"integer","minimum":0,"maximum":100,"description":"AI writing quality score (higher = less generic AI patterns)"},"ai_search_score":{"type":"integer","minimum":0,"maximum":100,"description":"AI search optimization (E-E-A-T signals, direct answers, etc.)"},"structure_score":{"type":"integer","minimum":0,"maximum":100},"technical_score":{"type":"integer","minimum":0,"maximum":100},"word_count":{"type":"integer","nullable":true},"target_keyword":{"type":"string","nullable":true},"graded_at":{"type":"string","format":"date-time"},"grader_version":{"type":"string"},"has_serp_data":{"type":"boolean","description":"Whether SERP optimization analysis is included"},"serp_score":{"type":"object","nullable":true,"description":"SERP optimization scores (only present if has_serp_data is true)","properties":{"overall":{"type":"number"},"term_coverage":{"type":"number","description":"Coverage of competitor terms in article"},"intent_alignment":{"type":"number","description":"How well content matches search intent"},"structure_match":{"type":"number","description":"Similarity to top-ranking content structure"},"paa_coverage":{"type":"number","description":"Coverage of People Also Ask questions"}}}}}}},"paths":{"/v1/contents/{id}/grade":{"post":{"summary":"Trigger grading for an article","description":"Analyzes the article and generates a content grade. Requires Power plan or higher.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The article ID"}],"responses":{"200":{"description":"Article graded successfully","content":{"application/json":{"schema":{"type":"object","properties":{"grade":{"$ref":"#/components/schemas/ContentGrade"},"exists":{"type":"boolean"}}}}}}},"tags":["Contents"]}}}}
```

## Get SERP analysis data for an article

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Contents","description":"Create and manage articles"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"SerpData":{"type":"object","nullable":true,"description":"SERP competitor analysis data","properties":{"id":{"type":"string","format":"uuid"},"article_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","complete","failed"]},"target_keyword":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"competitor_count":{"type":"integer"},"avg_word_count":{"type":"integer","nullable":true},"keyword_intent":{"type":"string","nullable":true,"enum":["informational","commercial","transactional","navigational"]},"paa_questions":{"type":"array","items":{"type":"string"},"description":"People Also Ask questions"},"top_competitors":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer"},"url":{"type":"string"},"title":{"type":"string"},"word_count":{"type":"integer","nullable":true}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/contents/{id}/serp":{"get":{"summary":"Get SERP analysis data for an article","description":"Returns competitor analysis data including top-ranking pages, word counts, and search intent.\nRequires Power plan or higher.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The article ID"}],"responses":{"200":{"description":"SERP analysis data","content":{"application/json":{"schema":{"type":"object","properties":{"serp_data":{"$ref":"#/components/schemas/SerpData"},"status":{"type":"string","enum":["not_fetched","pending","complete","failed"]}}}}}}},"tags":["Contents"]}}}}
```

## Fetch SERP data for an article

> 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.<br>

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Contents","description":"Create and manage articles"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/contents/{id}/serp":{"post":{"summary":"Fetch SERP data for an article","description":"Triggers competitor analysis by scraping top 10 search results for the article's keyword.\nData is cached for 3 days. Requires Power plan or higher.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The article ID"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"location":{"type":"string","description":"Country/region code (e.g. \"us\", \"uk\"). Required if not set on article."}}}}}},"responses":{"200":{"description":"SERP fetch started","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"status":{"type":"string"},"article_id":{"type":"string"}}}}}}},"tags":["Contents"]}}}}
```

## Get AI optimization suggestions

> 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.<br>

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Contents","description":"Create and manage articles"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"OptimizationResult":{"type":"object","description":"AI-powered optimization suggestions based on SERP analysis","properties":{"mode":{"type":"string","enum":["ai","quick"],"description":"Whether AI or quick rule-based suggestions were used"},"summary":{"type":"string"},"estimated_score_improvement":{"type":"integer"},"suggestions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["content","structure","seo","readability"]},"priority":{"type":"string","enum":["high","medium","low"]},"title":{"type":"string"},"description":{"type":"string"},"content":{"type":"string","nullable":true,"description":"Suggested content to add/modify"},"location":{"type":"string","nullable":true,"description":"Where in the article to apply this suggestion"},"impact_score":{"type":"number","nullable":true},"terms":{"type":"array","items":{"type":"string"},"description":"Related terms for this suggestion"}}}},"serp_analysis":{"type":"object","properties":{"overall_score":{"type":"number"},"term_coverage":{"type":"number"},"intent_alignment":{"type":"number"},"structure_match":{"type":"number"},"paa_coverage":{"type":"number"},"missing_terms":{"type":"array","items":{"type":"string"}},"missing_topics":{"type":"array","items":{"type":"string"}},"unanswered_questions":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/v1/contents/{id}/optimize":{"post":{"summary":"Get AI optimization suggestions","description":"Generates actionable suggestions to improve content based on SERP competitor analysis.\nRequires SERP data to be fetched first (POST /v1/contents/{id}/serp).\nUses Anthropic API key if available for AI-powered suggestions, otherwise returns quick suggestions.\nRequires Power plan or higher.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The article ID"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"use_ai":{"type":"boolean","default":true,"description":"Use AI for suggestions (requires Anthropic API key)"}}}}}},"responses":{"200":{"description":"Optimization suggestions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptimizationResult"}}}}},"tags":["Contents"]}}}}
```

## GET /v1/projects

> Fetch list of projects

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Bulk content generation projects"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/projects":{"get":{"summary":"Fetch list of projects","responses":{"200":{"description":"A list of projects","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}}}},"tags":["Projects"]}}}}
```

## POST /v1/projects

> Create a new project

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Bulk content generation projects"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"ContentSettings":{"type":"object","required":["language","region"],"properties":{"language":{"type":"string","description":"The language of the article."},"region":{"type":"string","description":"The region of the article."},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"],"default":"seo_optimized","description":"The tone of the article."},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"],"default":"first_person_plural","description":"The point of view of the article."},"article_type":{"type":"string","enum":["general","listicle","review","howto","recipe"],"default":"general","description":"The type of the article."},"fetch_perplexity":{"type":"boolean","default":false,"description":"Whether to use Perplexity for fetching real-time research data. It requires a Perplexity API key."},"include_introduction":{"type":"boolean","default":true,"description":"Whether to include an introduction section in the article."},"include_conclusion":{"type":"boolean","default":true,"description":"Whether to include a conclusion section in the article."},"include_yt_suggestions":{"type":"boolean","default":false,"description":"Whether to include YouTube suggestions in the article."},"generate_faqs":{"type":"boolean","default":false,"description":"Whether to generate a FAQ section in the article."},"generate_meta_description":{"type":"boolean","default":false,"description":"Whether to generate a meta description for the article."},"key_takeaways_position":{"type":"string","default":"none","enum":["top","bottom","none"],"description":"The position of the key takeaways section in the article. Use `none` to disable it."},"include_stock_images":{"type":"boolean","default":false,"description":"Whether to include stock featured images in the article."},"generate_images":{"type":"boolean","default":false,"description":"Whether to generate AI images for the article. Use the `image_settings` object to configure image generation."},"image_settings":{"type":"object","properties":{"model":{"type":"string","default":"gpt-image-1","description":"The image model to use for generation. Use the `/v1/meta/image_models` endpoint to get available image models."},"max_body_images_count":{"type":"integer","minimum":0,"maximum":7,"description":"The maximum number of images to generate in the body. Use `0` to disable body images."},"style_preset":{"type":"string","enum":["vintage","professional","photorealistic","infographic","minimalist_art","comic","watercolor_painting","abstract_art","pop_art","model_3d","line_art"],"nullable":true,"default":"photorealistic","description":"The style preset for the images. Use `custom_style` if you prefer a custom style instead."},"custom_style":{"type":"object","required":["name","description"],"properties":{"name":{"type":"string","description":"The name of the custom style."},"description":{"type":"string","description":"The description of the custom style. This should be a short but detailed description of the style you want to apply to the images."}},"description":"The custom style for the images."}}},"advanced_settings":{"type":"object","properties":{"title_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the title."},"introduction_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the introduction."},"section_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the sections."},"meta_description_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the meta description."}}}}},"Project":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"articles":{"type":"object","description":"A record of article IDs and their corresponding task status","additionalProperties":{"$ref":"#/components/schemas/TaskStatus"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}},"paths":{"/v1/projects":{"post":{"summary":"Create a new project","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_name":{"type":"string","description":"Name of the project","maxLength":100},"site_id":{"type":"string","format":"uuid","nullable":true,"description":"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."},"model":{"type":"string","description":"The model to use for the article. Use the `/v1/meta/models` endpoint to get available models.","default":"gpt-4o-mini"},"common_settings_preset":{"type":"number","description":"The settings preset to use for the project. Use the `common_settings` object to override specific settings. Go to your [presets](https://app.cuppa.ai/presets/my) to create a preset.","nullable":true},"common_settings":{"$ref":"#/components/schemas/ContentSettings","description":"The common settings to use for the project. Use the `common_settings_preset` property to specify a preset."},"target_keywords":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":600,"description":"The target keywords to generate content for."}},"required":["project_name","target_keywords"]}}}},"responses":{"200":{"description":"Project created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}}},"tags":["Projects"]}}}}
```

## GET /v1/projects/{id}

> Get a project by ID

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Bulk content generation projects"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Project":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"articles":{"type":"object","description":"A record of article IDs and their corresponding task status","additionalProperties":{"$ref":"#/components/schemas/TaskStatus"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}},"paths":{"/v1/projects/{id}":{"get":{"summary":"Get a project by ID","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The ID of the project"}],"responses":{"200":{"description":"The project object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}}},"tags":["Projects"]}}}}
```

## Export project articles

> 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.<br>

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Bulk content generation projects"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"ExportedArticle":{"type":"object","description":"An exported article with the requested fields","properties":{"title":{"type":"string","description":"The article title"},"slug":{"type":"string","description":"URL-friendly slug derived from the target keyword"},"content":{"type":"string","description":"The full HTML content of the article"},"excerpt":{"type":"string","nullable":true,"description":"The meta description or excerpt"},"date":{"type":"string","format":"date-time","description":"The article creation date"},"image":{"type":"string","nullable":true,"description":"URL of the featured image"},"target_keyword":{"type":"string","description":"The target keyword for the article"},"keywords":{"type":"string","nullable":true,"description":"Additional keywords"},"language":{"type":"string","description":"The language of the article (e.g., \"English\")"},"model":{"type":"string","description":"The AI model used for generation"},"pov":{"type":"string","description":"The point of view (e.g., \"First Person Plural\")"},"tone":{"type":"string","description":"The tone of voice (e.g., \"Professional\")"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}}}}}}},"paths":{"/v1/projects/{id}/export":{"get":{"summary":"Export project articles","description":"Export all completed articles from a project in JSON or CSV format. \nThis endpoint is useful for bulk exporting content to external systems like Airtable, spreadsheets, or custom CMS integrations.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The ID of the project to export"},{"in":"query","name":"format","schema":{"type":"string","enum":["json","csv"],"default":"json"},"description":"The export format. Use `csv` for spreadsheet-compatible output."},{"in":"query","name":"fields","schema":{"type":"string"},"description":"Comma-separated list of fields to include in the export. \nAvailable fields: `title`, `slug`, `content`, `excerpt`, `date`, `image`, `target_keyword`, `keywords`, `language`, `model`, `pov`, `tone`.\nDefault: `title,slug,content,excerpt,image,target_keyword,language,model`\n"},{"in":"query","name":"session_id","schema":{"type":"string","nullable":true},"description":"Filter articles by bulk session ID (optional)"},{"in":"query","name":"status","schema":{"type":"string","enum":["complete","all"],"default":"complete"},"description":"Filter by article status. Use `complete` to only export finished articles, or `all` to include in-progress articles."}],"responses":{"200":{"description":"Exported articles","content":{"application/json":{"schema":{"type":"object","properties":{"articles":{"type":"array","items":{"$ref":"#/components/schemas/ExportedArticle"}}}}},"text/csv":{"schema":{"type":"string","description":"CSV formatted article data"}}}},"404":{"description":"No articles found for this project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Projects"]}}}}
```

## List all sites/brands

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Sites","description":"Site/brand management and Brand DNA"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Site":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string","description":"The domain/URL of the site"},"icon_url":{"type":"string","nullable":true,"description":"URL to the site favicon or icon"},"status":{"type":"string","enum":["active","inactive"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/sites":{"get":{"summary":"List all sites/brands","description":"Returns a list of all sites (brands) for your team. Use site IDs when creating content to enable Brand DNA features.","parameters":[{"in":"query","name":"page","schema":{"type":"integer"},"description":"Page number for pagination"}],"responses":{"200":{"description":"A list of sites","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Site"}}}}}},"tags":["Sites"]}}}}
```

## GET /v1/sites/{id}

> Get a site by ID

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Sites","description":"Site/brand management and Brand DNA"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Site":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string","description":"The domain/URL of the site"},"icon_url":{"type":"string","nullable":true,"description":"URL to the site favicon or icon"},"status":{"type":"string","enum":["active","inactive"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/sites/{id}":{"get":{"summary":"Get a site by ID","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The site ID"}],"responses":{"200":{"description":"The site object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}}},"tags":["Sites"]}}}}
```

## Get all brand information for a site

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Sites","description":"Site/brand management and Brand DNA"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"BrandContext":{"type":"object","properties":{"company_name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true,"description":"Company/brand description"},"industry":{"type":"string","nullable":true},"target_audience":{"type":"string","nullable":true},"value_proposition":{"type":"string","nullable":true},"competitors":{"type":"object","nullable":true,"description":"JSON object containing competitor information"},"ranking_keywords":{"type":"object","nullable":true,"description":"JSON object containing keyword data"},"pain_points":{"type":"object","nullable":true,"description":"JSON object containing customer pain points"},"faq_questions":{"type":"object","nullable":true,"description":"JSON object containing FAQ data"}}},"BrandVoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"values":{"type":"object","description":"JSON object containing voice parameters (tone, persona, formality, vocabulary_style, sentence_structure, etc.)"}}},"BrandVisualStyle":{"type":"object","properties":{"logo_url":{"type":"string","nullable":true},"primary_color":{"type":"string","nullable":true},"secondary_color":{"type":"string","nullable":true},"accent_color":{"type":"string","nullable":true},"primary_font":{"type":"string","nullable":true},"visual_mood":{"type":"string","nullable":true}}}}},"paths":{"/v1/sites/{id}/brand":{"get":{"summary":"Get all brand information for a site","description":"Returns brand context, voices, and visual style in a single request.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The site ID"}],"responses":{"200":{"description":"Brand information","content":{"application/json":{"schema":{"type":"object","properties":{"context":{"$ref":"#/components/schemas/BrandContext"},"voices":{"type":"array","items":{"$ref":"#/components/schemas/BrandVoice"}},"visual_style":{"$ref":"#/components/schemas/BrandVisualStyle"}}}}}}},"tags":["Sites"]}}}}
```

## List all presets

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Presets","description":"Content generation presets"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Preset":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"target_content_type":{"type":"string","enum":["general","location_page"],"nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/presets":{"get":{"summary":"List all presets","description":"Returns a list of AI instruction presets that can be used when creating content.","parameters":[{"in":"query","name":"page","schema":{"type":"integer"},"description":"Page number for pagination"}],"responses":{"200":{"description":"A list of presets","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Preset"}}}}}},"tags":["Presets"]}}}}
```

## POST /v1/presets

> Create a new preset

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Presets","description":"Content generation presets"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"CreatePreset":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":500},"presets":{"type":"object","description":"Preset settings. All fields are optional.","properties":{"language":{"type":"string"},"location":{"type":"string"},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"]},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"]},"article_type":{"type":"string","enum":["general","listicle","review","howto"]},"target_length":{"type":"string","enum":["short","medium","long"]},"include_ai_images":{"type":"boolean"},"ai_image_meta":{"type":"object","description":"Image generation settings.","properties":{"image_model":{"type":"string"},"image_style":{"type":"string"},"image_count_body":{"type":"integer","minimum":0,"maximum":20},"use_brand_colors":{"type":"boolean"},"image_extra_prompt":{"type":"string"}}},"include_introduction":{"type":"boolean"},"include_conclusion":{"type":"boolean"},"include_faq":{"type":"boolean"},"include_meta_description":{"type":"boolean"},"extra_prompt":{"type":"string","maxLength":50000},"knowledge_sources":{"type":"array","items":{"type":"integer"}}}}}},"PresetDetail":{"allOf":[{"$ref":"#/components/schemas/Preset"},{"type":"object","properties":{"presets":{"type":"object","properties":{"language":{"type":"string"},"location":{"type":"string"},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"]},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"]},"article_type":{"type":"string","enum":["general","listicle","review","howto"]},"target_length":{"type":"string","enum":["short","medium","long"]},"enable_pplx_fetch":{"type":"boolean"},"include_introduction":{"type":"boolean"},"include_conclusion":{"type":"boolean"},"include_faq":{"type":"boolean"},"include_featured_image":{"type":"boolean"},"include_meta_description":{"type":"boolean"},"include_youtube_videos":{"type":"boolean"},"position_key_takeaways":{"type":"string","enum":["none","top","bottom"]},"include_ai_images":{"type":"boolean"},"ai_image_meta":{"type":"object","description":"Image generation settings stored in the preset.","properties":{"image_model":{"type":"string","description":"Image model (e.g. gpt-image-1, flux-schnell, flux-dev, flux-pro)"},"image_style":{"type":"string","description":"Image style (professional, photorealistic, cinematic, auto, etc.)"},"image_count_body":{"type":"integer","minimum":0,"maximum":20,"description":"Max number of images in the article body"},"use_brand_colors":{"type":"boolean","description":"Apply brand kit colors to generated images"},"image_extra_prompt":{"type":"string","description":"Custom instructions for image generation"}}},"extra_prompt":{"type":"string"},"knowledge_sources":{"type":"array","items":{"type":"integer"}}}}}}]},"Preset":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"target_content_type":{"type":"string","enum":["general","location_page"],"nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/presets":{"post":{"summary":"Create a new preset","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePreset"}}}},"responses":{"201":{"description":"Preset created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresetDetail"}}}}},"tags":["Presets"]}}}}
```

## GET /v1/presets/{id}

> Get a preset by ID

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Presets","description":"Content generation presets"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"PresetDetail":{"allOf":[{"$ref":"#/components/schemas/Preset"},{"type":"object","properties":{"presets":{"type":"object","properties":{"language":{"type":"string"},"location":{"type":"string"},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"]},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"]},"article_type":{"type":"string","enum":["general","listicle","review","howto"]},"target_length":{"type":"string","enum":["short","medium","long"]},"enable_pplx_fetch":{"type":"boolean"},"include_introduction":{"type":"boolean"},"include_conclusion":{"type":"boolean"},"include_faq":{"type":"boolean"},"include_featured_image":{"type":"boolean"},"include_meta_description":{"type":"boolean"},"include_youtube_videos":{"type":"boolean"},"position_key_takeaways":{"type":"string","enum":["none","top","bottom"]},"include_ai_images":{"type":"boolean"},"ai_image_meta":{"type":"object","description":"Image generation settings stored in the preset.","properties":{"image_model":{"type":"string","description":"Image model (e.g. gpt-image-1, flux-schnell, flux-dev, flux-pro)"},"image_style":{"type":"string","description":"Image style (professional, photorealistic, cinematic, auto, etc.)"},"image_count_body":{"type":"integer","minimum":0,"maximum":20,"description":"Max number of images in the article body"},"use_brand_colors":{"type":"boolean","description":"Apply brand kit colors to generated images"},"image_extra_prompt":{"type":"string","description":"Custom instructions for image generation"}}},"extra_prompt":{"type":"string"},"knowledge_sources":{"type":"array","items":{"type":"integer"}}}}}}]},"Preset":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"target_content_type":{"type":"string","enum":["general","location_page"],"nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/presets/{id}":{"get":{"summary":"Get a preset by ID","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer"},"description":"The preset ID"}],"responses":{"200":{"description":"The preset with full settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresetDetail"}}}}},"tags":["Presets"]}}}}
```

## PUT /v1/presets/{id}

> Update a preset

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Presets","description":"Content generation presets"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"CreatePreset":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":500},"presets":{"type":"object","description":"Preset settings. All fields are optional.","properties":{"language":{"type":"string"},"location":{"type":"string"},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"]},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"]},"article_type":{"type":"string","enum":["general","listicle","review","howto"]},"target_length":{"type":"string","enum":["short","medium","long"]},"include_ai_images":{"type":"boolean"},"ai_image_meta":{"type":"object","description":"Image generation settings.","properties":{"image_model":{"type":"string"},"image_style":{"type":"string"},"image_count_body":{"type":"integer","minimum":0,"maximum":20},"use_brand_colors":{"type":"boolean"},"image_extra_prompt":{"type":"string"}}},"include_introduction":{"type":"boolean"},"include_conclusion":{"type":"boolean"},"include_faq":{"type":"boolean"},"include_meta_description":{"type":"boolean"},"extra_prompt":{"type":"string","maxLength":50000},"knowledge_sources":{"type":"array","items":{"type":"integer"}}}}}},"PresetDetail":{"allOf":[{"$ref":"#/components/schemas/Preset"},{"type":"object","properties":{"presets":{"type":"object","properties":{"language":{"type":"string"},"location":{"type":"string"},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"]},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"]},"article_type":{"type":"string","enum":["general","listicle","review","howto"]},"target_length":{"type":"string","enum":["short","medium","long"]},"enable_pplx_fetch":{"type":"boolean"},"include_introduction":{"type":"boolean"},"include_conclusion":{"type":"boolean"},"include_faq":{"type":"boolean"},"include_featured_image":{"type":"boolean"},"include_meta_description":{"type":"boolean"},"include_youtube_videos":{"type":"boolean"},"position_key_takeaways":{"type":"string","enum":["none","top","bottom"]},"include_ai_images":{"type":"boolean"},"ai_image_meta":{"type":"object","description":"Image generation settings stored in the preset.","properties":{"image_model":{"type":"string","description":"Image model (e.g. gpt-image-1, flux-schnell, flux-dev, flux-pro)"},"image_style":{"type":"string","description":"Image style (professional, photorealistic, cinematic, auto, etc.)"},"image_count_body":{"type":"integer","minimum":0,"maximum":20,"description":"Max number of images in the article body"},"use_brand_colors":{"type":"boolean","description":"Apply brand kit colors to generated images"},"image_extra_prompt":{"type":"string","description":"Custom instructions for image generation"}}},"extra_prompt":{"type":"string"},"knowledge_sources":{"type":"array","items":{"type":"integer"}}}}}}]},"Preset":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"target_content_type":{"type":"string","enum":["general","location_page"],"nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/presets/{id}":{"put":{"summary":"Update a preset","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer"},"description":"The preset ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePreset"}}}},"responses":{"200":{"description":"Preset updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresetDetail"}}}}},"tags":["Presets"]}}}}
```

## List knowledge sources

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Knowledge","description":"Knowledge sources for RAG"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"KnowledgeSource":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"source_type":{"type":"string","enum":["text","file","url"]},"indexing":{"type":"object","nullable":true,"properties":{"chunks_indexed":{"type":"integer"},"total_chunks":{"type":"integer"},"was_limited":{"type":"boolean"},"indexed_at":{"type":"string","format":"date-time","nullable":true}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/knowledge":{"get":{"summary":"List knowledge sources","description":"Returns a list of knowledge sources (RAG documents). Requires Power plan or higher.","parameters":[{"in":"query","name":"page","schema":{"type":"integer"},"description":"Page number for pagination"}],"responses":{"200":{"description":"A list of knowledge sources","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeSource"}}}}}},"tags":["Knowledge"]}}}}
```

## DELETE /v1/presets/{id}

> Delete a preset

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Presets","description":"Content generation presets"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/presets/{id}":{"delete":{"summary":"Delete a preset","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer"},"description":"The preset ID"}],"responses":{"204":{"description":"Preset deleted"}},"tags":["Presets"]}}}}
```

## Create a text knowledge source

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Knowledge","description":"Knowledge sources for RAG"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"KnowledgeSource":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"source_type":{"type":"string","enum":["text","file","url"]},"indexing":{"type":"object","nullable":true,"properties":{"chunks_indexed":{"type":"integer"},"total_chunks":{"type":"integer"},"was_limited":{"type":"boolean"},"indexed_at":{"type":"string","format":"date-time","nullable":true}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/knowledge":{"post":{"summary":"Create a text knowledge source","description":"Create a knowledge source from text content. For file uploads, use POST /v1/knowledge/upload.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","content"],"properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":500},"content":{"type":"string","maxLength":100000,"description":"The text content to index"}}}}}},"responses":{"201":{"description":"Knowledge source created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeSource"}}}}},"tags":["Knowledge"]}}}}
```

## Request upload URL for file-based knowledge

> 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.<br>

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Knowledge","description":"Knowledge sources for RAG"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/knowledge/upload":{"post":{"summary":"Request upload URL for file-based knowledge","description":"Get a signed URL to upload a PDF or TXT file. After uploading, call POST /v1/knowledge/{id}/confirm to trigger processing.\nMaximum file size: 50MB.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","filename","content_type"],"properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":500},"filename":{"type":"string"},"content_type":{"type":"string","enum":["application/pdf","text/plain"]}}}}}},"responses":{"201":{"description":"Upload URL generated","content":{"application/json":{"schema":{"type":"object","properties":{"knowledge_id":{"type":"integer"},"upload_url":{"type":"string","description":"Signed URL for file upload"},"expires_at":{"type":"string","format":"date-time"}}}}}}},"tags":["Knowledge"]}}}}
```

## List keyword clusters

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Clusters","description":"Keyword cluster management"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Cluster":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"in_plan":{"type":"boolean","description":"Whether this cluster is active in content planning"},"pillar_page":{"type":"string","nullable":true,"description":"URL of the pillar page for this cluster"},"total_keywords":{"type":"integer"},"total_search_volume":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/clusters":{"get":{"summary":"List keyword clusters","description":"Returns keyword clusters for content planning. Requires Power plan or higher.","parameters":[{"in":"query","name":"page","schema":{"type":"integer"}},{"in":"query","name":"site","schema":{"type":"string","format":"uuid"},"description":"Filter by site ID"},{"in":"query","name":"in_plan","schema":{"type":"boolean"},"description":"Filter by active clusters"}],"responses":{"200":{"description":"A list of clusters","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Cluster"}}}}}},"tags":["Clusters"]}}}}
```

## GET /v1/clusters/{id}

> Get a cluster with keywords

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Clusters","description":"Keyword cluster management"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"ClusterDetail":{"allOf":[{"$ref":"#/components/schemas/Cluster"},{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"keyword":{"type":"string"},"search_volume":{"type":"integer","nullable":true},"keyword_difficulty":{"type":"number","nullable":true},"cpc":{"type":"number","nullable":true},"search_intent":{"type":"string","nullable":true},"article_id":{"type":"string","nullable":true,"description":"Article ID if content has been generated for this keyword"}}}}}}]},"Cluster":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"in_plan":{"type":"boolean","description":"Whether this cluster is active in content planning"},"pillar_page":{"type":"string","nullable":true,"description":"URL of the pillar page for this cluster"},"total_keywords":{"type":"integer"},"total_search_volume":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/clusters/{id}":{"get":{"summary":"Get a cluster with keywords","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The cluster ID"}],"responses":{"200":{"description":"Cluster with keywords","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterDetail"}}}}},"tags":["Clusters"]}}}}
```

## Activate a cluster

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Clusters","description":"Keyword cluster management"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Cluster":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"in_plan":{"type":"boolean","description":"Whether this cluster is active in content planning"},"pillar_page":{"type":"string","nullable":true,"description":"URL of the pillar page for this cluster"},"total_keywords":{"type":"integer"},"total_search_volume":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/clusters/{id}/activate":{"post":{"summary":"Activate a cluster","description":"Mark a cluster as \"In Plan\" for content planning. Requires Power plan or higher.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The cluster ID"}],"responses":{"200":{"description":"Cluster activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cluster"}}}}},"tags":["Clusters"]}}}}
```

## Deactivate a cluster

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Clusters","description":"Keyword cluster management"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Cluster":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"in_plan":{"type":"boolean","description":"Whether this cluster is active in content planning"},"pillar_page":{"type":"string","nullable":true,"description":"URL of the pillar page for this cluster"},"total_keywords":{"type":"integer"},"total_search_volume":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/clusters/{id}/deactivate":{"post":{"summary":"Deactivate a cluster","description":"Remove a cluster from \"In Plan\". Requires Power plan or higher.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The cluster ID"}],"responses":{"200":{"description":"Cluster deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cluster"}}}}},"tags":["Clusters"]}}}}
```

## List content planner items

> Returns scheduled content items. Requires Power plan or higher.

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Planner","description":"Content planning and scheduling"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"PlannerItem":{"type":"object","description":"Content planner item. Uses keyword_id as the unique identifier.","properties":{"keyword_id":{"type":"string","format":"uuid","description":"The unique identifier for this planner item (also the keyword ID)"},"site_id":{"type":"string","format":"uuid"},"cluster_id":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date","description":"Scheduled date for content creation"},"status":{"type":"string","enum":["scheduled","progress","created","published"]},"keyword":{"type":"string","nullable":true,"description":"The keyword text"},"cluster_title":{"type":"string","nullable":true,"description":"Title of the parent cluster"},"metadata":{"type":"object","nullable":true,"description":"Additional metadata (may contain article_id after content is created)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/planner":{"get":{"summary":"List content planner items","description":"Returns scheduled content items. Requires Power plan or higher.","parameters":[{"in":"query","name":"page","schema":{"type":"integer"}},{"in":"query","name":"site","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"status","schema":{"type":"string","enum":["scheduled","progress","created","published"]}},{"in":"query","name":"from_date","schema":{"type":"string","format":"date"},"description":"Filter items scheduled on or after this date"},{"in":"query","name":"to_date","schema":{"type":"string","format":"date"},"description":"Filter items scheduled on or before this date"}],"responses":{"200":{"description":"A list of planner items","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PlannerItem"}}}}}},"tags":["Planner"]}}}}
```

## Create a planner item

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Planner","description":"Content planning and scheduling"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"PlannerItem":{"type":"object","description":"Content planner item. Uses keyword_id as the unique identifier.","properties":{"keyword_id":{"type":"string","format":"uuid","description":"The unique identifier for this planner item (also the keyword ID)"},"site_id":{"type":"string","format":"uuid"},"cluster_id":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date","description":"Scheduled date for content creation"},"status":{"type":"string","enum":["scheduled","progress","created","published"]},"keyword":{"type":"string","nullable":true,"description":"The keyword text"},"cluster_title":{"type":"string","nullable":true,"description":"Title of the parent cluster"},"metadata":{"type":"object","nullable":true,"description":"Additional metadata (may contain article_id after content is created)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}}}}}}},"paths":{"/v1/planner":{"post":{"summary":"Create a planner item","description":"Schedule a keyword for content creation. Each keyword can only be scheduled once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site_id","keyword_id","cluster_id","date"],"properties":{"site_id":{"type":"string","format":"uuid"},"keyword_id":{"type":"string","format":"uuid","description":"The keyword to schedule (must exist in site_keywords)"},"cluster_id":{"type":"string","format":"uuid","description":"The cluster this keyword belongs to"},"date":{"type":"string","format":"date","description":"Scheduled date for content creation"},"status":{"type":"string","enum":["scheduled","progress","created","published"],"default":"scheduled"}}}}}},"responses":{"201":{"description":"Planner item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlannerItem"}}}},"409":{"description":"Planner item already exists for this keyword","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Planner"]}}}}
```

## Get a planner item

> Get a single planner item by keyword\_id. Requires Power plan or higher.

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Planner","description":"Content planning and scheduling"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"PlannerItem":{"type":"object","description":"Content planner item. Uses keyword_id as the unique identifier.","properties":{"keyword_id":{"type":"string","format":"uuid","description":"The unique identifier for this planner item (also the keyword ID)"},"site_id":{"type":"string","format":"uuid"},"cluster_id":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date","description":"Scheduled date for content creation"},"status":{"type":"string","enum":["scheduled","progress","created","published"]},"keyword":{"type":"string","nullable":true,"description":"The keyword text"},"cluster_title":{"type":"string","nullable":true,"description":"Title of the parent cluster"},"metadata":{"type":"object","nullable":true,"description":"Additional metadata (may contain article_id after content is created)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}}}}}}},"paths":{"/v1/planner/{id}":{"get":{"summary":"Get a planner item","description":"Get a single planner item by keyword_id. Requires Power plan or higher.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The keyword_id of the planner item"}],"responses":{"200":{"description":"The planner item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlannerItem"}}}},"404":{"description":"Planner item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Planner"]}}}}
```

## Update a planner item

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Planner","description":"Content planning and scheduling"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"PlannerItem":{"type":"object","description":"Content planner item. Uses keyword_id as the unique identifier.","properties":{"keyword_id":{"type":"string","format":"uuid","description":"The unique identifier for this planner item (also the keyword ID)"},"site_id":{"type":"string","format":"uuid"},"cluster_id":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date","description":"Scheduled date for content creation"},"status":{"type":"string","enum":["scheduled","progress","created","published"]},"keyword":{"type":"string","nullable":true,"description":"The keyword text"},"cluster_title":{"type":"string","nullable":true,"description":"Title of the parent cluster"},"metadata":{"type":"object","nullable":true,"description":"Additional metadata (may contain article_id after content is created)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}}}}}}},"paths":{"/v1/planner/{id}":{"put":{"summary":"Update a planner item","description":"Update the scheduled date or status of a planner item. Requires Power plan or higher.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The keyword_id of the planner item"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"New scheduled date"},"status":{"type":"string","enum":["scheduled","progress","created","published"],"description":"New status"}}}}}},"responses":{"200":{"description":"Planner item updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlannerItem"}}}},"400":{"description":"Invalid status transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Planner"]}}}}
```

## Delete a planner item

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Planner","description":"Content planning and scheduling"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}}}}}}},"paths":{"/v1/planner/{id}":{"delete":{"summary":"Delete a planner item","description":"Remove a scheduled item from the content planner. Cannot delete created/published items. Requires Power plan or higher.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The keyword_id of the planner item"}],"responses":{"200":{"description":"Planner item deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"description":"Cannot delete created or published items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Planner"]}}}}
```

## Generate a social media post

> Generate a social media post from article content or a standalone\
> topic. Provide article\_title + article\_summary, or just a topic.\
> Requires Power plan or higher. Uses your OpenAI API key for text\
> generation, and optionally Replicate API key for image generation.<br>

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Social","description":"Social media content generation and publishing"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"GenerateSocialPost":{"type":"object","required":["site_id","platform"],"description":"Provide article_title + article_summary for article-derived posts,\nor provide topic for standalone posts.\n","properties":{"site_id":{"type":"string","format":"uuid"},"article_id":{"type":"string","format":"uuid","nullable":true},"topic":{"type":"string","maxLength":500,"description":"Standalone topic (alternative to article_title/article_summary)"},"article_title":{"type":"string","description":"Required if topic not provided"},"article_summary":{"type":"string","description":"Required if topic not provided"},"article_url":{"type":"string","format":"uri","nullable":true},"platform":{"type":"string","enum":["twitter","instagram","facebook","linkedin","tiktok","youtube","pinterest","reddit","bluesky","threads"]},"tone":{"type":"string","enum":["casual","professional","witty","inspiring","educational","engaging"],"default":"engaging"},"include_hashtags":{"type":"boolean","default":true},"max_hashtags":{"type":"integer","minimum":0,"maximum":30},"hook_type":{"type":"string","enum":["curiosity","story","value","contrarian","social_proof"]},"generate_image":{"type":"boolean","default":false}}},"SocialPost":{"type":"object","properties":{"content":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"image_prompt":{"type":"string"},"image_url":{"type":"string","nullable":true},"platform":{"type":"string"},"character_count":{"type":"integer"},"hook":{"type":"string","nullable":true},"metadata":{"type":"object","properties":{"tokens_used":{"type":"integer"},"model":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"brand_context_used":{"type":"boolean"}}}}}}},"paths":{"/v1/social":{"post":{"summary":"Generate a social media post","description":"Generate a social media post from article content or a standalone\ntopic. Provide article_title + article_summary, or just a topic.\nRequires Power plan or higher. Uses your OpenAI API key for text\ngeneration, and optionally Replicate API key for image generation.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateSocialPost"}}}},"responses":{"201":{"description":"Social post generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SocialPost"}}}}},"tags":["Social"]}}}}
```

## Get supported social platforms

> Returns all supported platforms with character limits, format support, and content tips.<br>

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Social","description":"Social media content generation and publishing"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/social/platforms":{"get":{"summary":"Get supported social platforms","description":"Returns all supported platforms with character limits, format support, and content tips.\n","responses":{"200":{"description":"List of platforms","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"max_characters":{"type":"integer"},"hashtags_supported":{"type":"boolean"},"max_hashtags":{"type":"integer"},"best_practices":{"type":"string"},"content_tips":{"type":"string","description":"Platform-specific caption and hook guidance for Brand DNA and content tools"}}}}}}}}}},"tags":["Social"]}}}}
```

## List Link Engine sites

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Links","description":"Link Engine for internal linking"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"LinkEngineSite":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"link_engine_status":{"type":"string","enum":["active","paused","indexing","inactive","error"]},"link_engine_url_count":{"type":"integer"},"link_engine_last_indexed_at":{"type":"string","format":"date-time","nullable":true},"link_engine_error":{"type":"string","nullable":true},"category_id":{"type":"string","format":"uuid","nullable":true},"category_name":{"type":"string","nullable":true},"has_link_config":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}}},"paths":{"/v1/links":{"get":{"summary":"List Link Engine sites","description":"Returns sites with Link Engine configuration. Requires Power plan or higher.","parameters":[{"in":"query","name":"page","schema":{"type":"integer"}},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search by domain"},{"in":"query","name":"category","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"status","schema":{"type":"string","enum":["all","active","paused","indexing","inactive","error"]}}],"responses":{"200":{"description":"List of Link Engine sites","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LinkEngineSite"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"}}}}}}}}},"tags":["Links"]}}}}
```

## GET /v1/links/stats

> Get Link Engine statistics

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Links","description":"Link Engine for internal linking"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"LinkEngineStats":{"type":"object","properties":{"total_sites":{"type":"integer"},"active_sites":{"type":"integer"},"paused_sites":{"type":"integer"},"indexing_sites":{"type":"integer"},"error_sites":{"type":"integer"},"total_urls":{"type":"integer"}}}}},"paths":{"/v1/links/stats":{"get":{"summary":"Get Link Engine statistics","responses":{"200":{"description":"Link Engine stats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkEngineStats"}}}}},"tags":["Links"]}}}}
```

## GET /v1/links/categories

> List link categories

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Links","description":"Link Engine for internal linking"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"LinkCategory":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"color":{"type":"string"},"site_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}}}},"paths":{"/v1/links/categories":{"get":{"summary":"List link categories","responses":{"200":{"description":"List of categories","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LinkCategory"}}}}}},"tags":["Links"]}}}}
```

## POST /v1/links/categories

> Create a link category

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Links","description":"Link Engine for internal linking"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"LinkCategory":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"color":{"type":"string"},"site_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}}}},"paths":{"/v1/links/categories":{"post":{"summary":"Create a link category","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":50},"description":{"type":"string","maxLength":200},"color":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","default":"#6366f1"}}}}}},"responses":{"201":{"description":"Category created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkCategory"}}}}},"tags":["Links"]}}}}
```

## The Error object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}}}}}}}}
```

## The TaskStatus object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}}}
```

## The Content object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"Content":{"type":"object","properties":{"id":{"type":"string"},"is_draft":{"type":"boolean","description":"Whether the article is a draft"},"status":{"$ref":"#/components/schemas/TaskStatus"},"title":{"type":"string","nullable":true,"description":"It is null if the article is not generated yet."},"content":{"type":"string","nullable":true,"description":"It is null if the article is not generated yet."},"snippet":{"type":"string","nullable":true},"project_id":{"type":"string","nullable":true,"description":"It is null if the article is not part of a project."},"site_id":{"type":"string","format":"uuid","nullable":true,"description":"The site/brand ID associated with this article. Null if no brand context."},"meta_description":{"type":"string","nullable":true},"featured_images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"alt":{"type":"string","nullable":true}}}},"content_type":{"type":"string","enum":["article"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"target_keyword":{"type":"string"},"language":{"type":"string"},"region":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}}}
```

## The ContentSettings object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"ContentSettings":{"type":"object","required":["language","region"],"properties":{"language":{"type":"string","description":"The language of the article."},"region":{"type":"string","description":"The region of the article."},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"],"default":"seo_optimized","description":"The tone of the article."},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"],"default":"first_person_plural","description":"The point of view of the article."},"article_type":{"type":"string","enum":["general","listicle","review","howto","recipe"],"default":"general","description":"The type of the article."},"fetch_perplexity":{"type":"boolean","default":false,"description":"Whether to use Perplexity for fetching real-time research data. It requires a Perplexity API key."},"include_introduction":{"type":"boolean","default":true,"description":"Whether to include an introduction section in the article."},"include_conclusion":{"type":"boolean","default":true,"description":"Whether to include a conclusion section in the article."},"include_yt_suggestions":{"type":"boolean","default":false,"description":"Whether to include YouTube suggestions in the article."},"generate_faqs":{"type":"boolean","default":false,"description":"Whether to generate a FAQ section in the article."},"generate_meta_description":{"type":"boolean","default":false,"description":"Whether to generate a meta description for the article."},"key_takeaways_position":{"type":"string","default":"none","enum":["top","bottom","none"],"description":"The position of the key takeaways section in the article. Use `none` to disable it."},"include_stock_images":{"type":"boolean","default":false,"description":"Whether to include stock featured images in the article."},"generate_images":{"type":"boolean","default":false,"description":"Whether to generate AI images for the article. Use the `image_settings` object to configure image generation."},"image_settings":{"type":"object","properties":{"model":{"type":"string","default":"gpt-image-1","description":"The image model to use for generation. Use the `/v1/meta/image_models` endpoint to get available image models."},"max_body_images_count":{"type":"integer","minimum":0,"maximum":7,"description":"The maximum number of images to generate in the body. Use `0` to disable body images."},"style_preset":{"type":"string","enum":["vintage","professional","photorealistic","infographic","minimalist_art","comic","watercolor_painting","abstract_art","pop_art","model_3d","line_art"],"nullable":true,"default":"photorealistic","description":"The style preset for the images. Use `custom_style` if you prefer a custom style instead."},"custom_style":{"type":"object","required":["name","description"],"properties":{"name":{"type":"string","description":"The name of the custom style."},"description":{"type":"string","description":"The description of the custom style. This should be a short but detailed description of the style you want to apply to the images."}},"description":"The custom style for the images."}}},"advanced_settings":{"type":"object","properties":{"title_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the title."},"introduction_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the introduction."},"section_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the sections."},"meta_description_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the meta description."}}}}}}}}
```

## The ContentStatusResponse object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"ContentStatusResponse":{"type":"object","properties":{"id":{"type":"string"},"is_draft":{"type":"boolean","description":"Whether the article is a draft"},"status":{"$ref":"#/components/schemas/TaskStatus"},"status_extra":{"type":"object","properties":{"error":{"type":"string","nullable":true,"description":"Error message if status is failed"}}}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}}}
```

## The Project object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"Project":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"articles":{"type":"object","description":"A record of article IDs and their corresponding task status","additionalProperties":{"$ref":"#/components/schemas/TaskStatus"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}}}
```

## The ExportedArticle object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"ExportedArticle":{"type":"object","description":"An exported article with the requested fields","properties":{"title":{"type":"string","description":"The article title"},"slug":{"type":"string","description":"URL-friendly slug derived from the target keyword"},"content":{"type":"string","description":"The full HTML content of the article"},"excerpt":{"type":"string","nullable":true,"description":"The meta description or excerpt"},"date":{"type":"string","format":"date-time","description":"The article creation date"},"image":{"type":"string","nullable":true,"description":"URL of the featured image"},"target_keyword":{"type":"string","description":"The target keyword for the article"},"keywords":{"type":"string","nullable":true,"description":"Additional keywords"},"language":{"type":"string","description":"The language of the article (e.g., \"English\")"},"model":{"type":"string","description":"The AI model used for generation"},"pov":{"type":"string","description":"The point of view (e.g., \"First Person Plural\")"},"tone":{"type":"string","description":"The tone of voice (e.g., \"Professional\")"}}}}}}
```

## The Site object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"Site":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string","description":"The domain/URL of the site"},"icon_url":{"type":"string","nullable":true,"description":"URL to the site favicon or icon"},"status":{"type":"string","enum":["active","inactive"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}}
```

## The BrandContext object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"BrandContext":{"type":"object","properties":{"company_name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true,"description":"Company/brand description"},"industry":{"type":"string","nullable":true},"target_audience":{"type":"string","nullable":true},"value_proposition":{"type":"string","nullable":true},"competitors":{"type":"object","nullable":true,"description":"JSON object containing competitor information"},"ranking_keywords":{"type":"object","nullable":true,"description":"JSON object containing keyword data"},"pain_points":{"type":"object","nullable":true,"description":"JSON object containing customer pain points"},"faq_questions":{"type":"object","nullable":true,"description":"JSON object containing FAQ data"}}}}}}
```

## The BrandVoice object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"BrandVoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"values":{"type":"object","description":"JSON object containing voice parameters (tone, persona, formality, vocabulary_style, sentence_structure, etc.)"}}}}}}
```

## The BrandVisualStyle object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"BrandVisualStyle":{"type":"object","properties":{"logo_url":{"type":"string","nullable":true},"primary_color":{"type":"string","nullable":true},"secondary_color":{"type":"string","nullable":true},"accent_color":{"type":"string","nullable":true},"primary_font":{"type":"string","nullable":true},"visual_mood":{"type":"string","nullable":true}}}}}}
```

## The Preset object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"Preset":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"target_content_type":{"type":"string","enum":["general","location_page"],"nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}}
```

## The PresetDetail object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"PresetDetail":{"allOf":[{"$ref":"#/components/schemas/Preset"},{"type":"object","properties":{"presets":{"type":"object","properties":{"language":{"type":"string"},"location":{"type":"string"},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"]},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"]},"article_type":{"type":"string","enum":["general","listicle","review","howto"]},"target_length":{"type":"string","enum":["short","medium","long"]},"enable_pplx_fetch":{"type":"boolean"},"include_introduction":{"type":"boolean"},"include_conclusion":{"type":"boolean"},"include_faq":{"type":"boolean"},"include_featured_image":{"type":"boolean"},"include_meta_description":{"type":"boolean"},"include_youtube_videos":{"type":"boolean"},"position_key_takeaways":{"type":"string","enum":["none","top","bottom"]},"include_ai_images":{"type":"boolean"},"ai_image_meta":{"type":"object","description":"Image generation settings stored in the preset.","properties":{"image_model":{"type":"string","description":"Image model (e.g. gpt-image-1, flux-schnell, flux-dev, flux-pro)"},"image_style":{"type":"string","description":"Image style (professional, photorealistic, cinematic, auto, etc.)"},"image_count_body":{"type":"integer","minimum":0,"maximum":20,"description":"Max number of images in the article body"},"use_brand_colors":{"type":"boolean","description":"Apply brand kit colors to generated images"},"image_extra_prompt":{"type":"string","description":"Custom instructions for image generation"}}},"extra_prompt":{"type":"string"},"knowledge_sources":{"type":"array","items":{"type":"integer"}}}}}}]},"Preset":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"target_content_type":{"type":"string","enum":["general","location_page"],"nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}}
```

## The CreatePreset object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"CreatePreset":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":500},"presets":{"type":"object","description":"Preset settings. All fields are optional.","properties":{"language":{"type":"string"},"location":{"type":"string"},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"]},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"]},"article_type":{"type":"string","enum":["general","listicle","review","howto"]},"target_length":{"type":"string","enum":["short","medium","long"]},"include_ai_images":{"type":"boolean"},"ai_image_meta":{"type":"object","description":"Image generation settings.","properties":{"image_model":{"type":"string"},"image_style":{"type":"string"},"image_count_body":{"type":"integer","minimum":0,"maximum":20},"use_brand_colors":{"type":"boolean"},"image_extra_prompt":{"type":"string"}}},"include_introduction":{"type":"boolean"},"include_conclusion":{"type":"boolean"},"include_faq":{"type":"boolean"},"include_meta_description":{"type":"boolean"},"extra_prompt":{"type":"string","maxLength":50000},"knowledge_sources":{"type":"array","items":{"type":"integer"}}}}}}}}}
```

## The KnowledgeSource object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"KnowledgeSource":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"source_type":{"type":"string","enum":["text","file","url"]},"indexing":{"type":"object","nullable":true,"properties":{"chunks_indexed":{"type":"integer"},"total_chunks":{"type":"integer"},"was_limited":{"type":"boolean"},"indexed_at":{"type":"string","format":"date-time","nullable":true}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}}
```

## The Cluster object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"Cluster":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"in_plan":{"type":"boolean","description":"Whether this cluster is active in content planning"},"pillar_page":{"type":"string","nullable":true,"description":"URL of the pillar page for this cluster"},"total_keywords":{"type":"integer"},"total_search_volume":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}}
```

## The ClusterDetail object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"ClusterDetail":{"allOf":[{"$ref":"#/components/schemas/Cluster"},{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"keyword":{"type":"string"},"search_volume":{"type":"integer","nullable":true},"keyword_difficulty":{"type":"number","nullable":true},"cpc":{"type":"number","nullable":true},"search_intent":{"type":"string","nullable":true},"article_id":{"type":"string","nullable":true,"description":"Article ID if content has been generated for this keyword"}}}}}}]},"Cluster":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"in_plan":{"type":"boolean","description":"Whether this cluster is active in content planning"},"pillar_page":{"type":"string","nullable":true,"description":"URL of the pillar page for this cluster"},"total_keywords":{"type":"integer"},"total_search_volume":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}}
```

## The PlannerItem object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"PlannerItem":{"type":"object","description":"Content planner item. Uses keyword_id as the unique identifier.","properties":{"keyword_id":{"type":"string","format":"uuid","description":"The unique identifier for this planner item (also the keyword ID)"},"site_id":{"type":"string","format":"uuid"},"cluster_id":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date","description":"Scheduled date for content creation"},"status":{"type":"string","enum":["scheduled","progress","created","published"]},"keyword":{"type":"string","nullable":true,"description":"The keyword text"},"cluster_title":{"type":"string","nullable":true,"description":"Title of the parent cluster"},"metadata":{"type":"object","nullable":true,"description":"Additional metadata (may contain article_id after content is created)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}}
```

## The GenerateSocialPost object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"GenerateSocialPost":{"type":"object","required":["site_id","platform"],"description":"Provide article_title + article_summary for article-derived posts,\nor provide topic for standalone posts.\n","properties":{"site_id":{"type":"string","format":"uuid"},"article_id":{"type":"string","format":"uuid","nullable":true},"topic":{"type":"string","maxLength":500,"description":"Standalone topic (alternative to article_title/article_summary)"},"article_title":{"type":"string","description":"Required if topic not provided"},"article_summary":{"type":"string","description":"Required if topic not provided"},"article_url":{"type":"string","format":"uri","nullable":true},"platform":{"type":"string","enum":["twitter","instagram","facebook","linkedin","tiktok","youtube","pinterest","reddit","bluesky","threads"]},"tone":{"type":"string","enum":["casual","professional","witty","inspiring","educational","engaging"],"default":"engaging"},"include_hashtags":{"type":"boolean","default":true},"max_hashtags":{"type":"integer","minimum":0,"maximum":30},"hook_type":{"type":"string","enum":["curiosity","story","value","contrarian","social_proof"]},"generate_image":{"type":"boolean","default":false}}}}}}
```

## The SocialPost object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"SocialPost":{"type":"object","properties":{"content":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"image_prompt":{"type":"string"},"image_url":{"type":"string","nullable":true},"platform":{"type":"string"},"character_count":{"type":"integer"},"hook":{"type":"string","nullable":true},"metadata":{"type":"object","properties":{"tokens_used":{"type":"integer"},"model":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"brand_context_used":{"type":"boolean"}}}}}}}}
```

## The LinkEngineSite object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"LinkEngineSite":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"link_engine_status":{"type":"string","enum":["active","paused","indexing","inactive","error"]},"link_engine_url_count":{"type":"integer"},"link_engine_last_indexed_at":{"type":"string","format":"date-time","nullable":true},"link_engine_error":{"type":"string","nullable":true},"category_id":{"type":"string","format":"uuid","nullable":true},"category_name":{"type":"string","nullable":true},"has_link_config":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}}}}
```

## The LinkEngineStats object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"LinkEngineStats":{"type":"object","properties":{"total_sites":{"type":"integer"},"active_sites":{"type":"integer"},"paused_sites":{"type":"integer"},"indexing_sites":{"type":"integer"},"error_sites":{"type":"integer"},"total_urls":{"type":"integer"}}}}}}
```

## The LinkCategory object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"LinkCategory":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"color":{"type":"string"},"site_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}}}}}
```

## The SerpData object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"SerpData":{"type":"object","nullable":true,"description":"SERP competitor analysis data","properties":{"id":{"type":"string","format":"uuid"},"article_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","complete","failed"]},"target_keyword":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"competitor_count":{"type":"integer"},"avg_word_count":{"type":"integer","nullable":true},"keyword_intent":{"type":"string","nullable":true,"enum":["informational","commercial","transactional","navigational"]},"paa_questions":{"type":"array","items":{"type":"string"},"description":"People Also Ask questions"},"top_competitors":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer"},"url":{"type":"string"},"title":{"type":"string"},"word_count":{"type":"integer","nullable":true}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}}
```

## The OptimizationResult object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"OptimizationResult":{"type":"object","description":"AI-powered optimization suggestions based on SERP analysis","properties":{"mode":{"type":"string","enum":["ai","quick"],"description":"Whether AI or quick rule-based suggestions were used"},"summary":{"type":"string"},"estimated_score_improvement":{"type":"integer"},"suggestions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["content","structure","seo","readability"]},"priority":{"type":"string","enum":["high","medium","low"]},"title":{"type":"string"},"description":{"type":"string"},"content":{"type":"string","nullable":true,"description":"Suggested content to add/modify"},"location":{"type":"string","nullable":true,"description":"Where in the article to apply this suggestion"},"impact_score":{"type":"number","nullable":true},"terms":{"type":"array","items":{"type":"string"},"description":"Related terms for this suggestion"}}}},"serp_analysis":{"type":"object","properties":{"overall_score":{"type":"number"},"term_coverage":{"type":"number"},"intent_alignment":{"type":"number"},"structure_match":{"type":"number"},"paa_coverage":{"type":"number"},"missing_terms":{"type":"array","items":{"type":"string"}},"missing_topics":{"type":"array","items":{"type":"string"}},"unanswered_questions":{"type":"array","items":{"type":"string"}}}}}}}}}
```

## The ContentGrade object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"ContentGrade":{"type":"object","description":"Content grade with SEO, readability, and SERP optimization scores","properties":{"overall_score":{"type":"integer","minimum":0,"maximum":100,"description":"Weighted average of all category scores"},"seo_score":{"type":"integer","minimum":0,"maximum":100},"readability_score":{"type":"integer","minimum":0,"maximum":100},"slop_score":{"type":"integer","minimum":0,"maximum":100,"description":"AI writing quality score (higher = less generic AI patterns)"},"ai_search_score":{"type":"integer","minimum":0,"maximum":100,"description":"AI search optimization (E-E-A-T signals, direct answers, etc.)"},"structure_score":{"type":"integer","minimum":0,"maximum":100},"technical_score":{"type":"integer","minimum":0,"maximum":100},"word_count":{"type":"integer","nullable":true},"target_keyword":{"type":"string","nullable":true},"graded_at":{"type":"string","format":"date-time"},"grader_version":{"type":"string"},"has_serp_data":{"type":"boolean","description":"Whether SERP optimization analysis is included"},"serp_score":{"type":"object","nullable":true,"description":"SERP optimization scores (only present if has_serp_data is true)","properties":{"overall":{"type":"number"},"term_coverage":{"type":"number","description":"Coverage of competitor terms in article"},"intent_alignment":{"type":"number","description":"How well content matches search intent"},"structure_match":{"type":"number","description":"Similarity to top-ranking content structure"},"paa_coverage":{"type":"number","description":"Coverage of People Also Ask questions"}}}}}}}}
```

#### Authentication

To use the API, you need to authenticate using an API key. Go to your Cuppa [settings](https://app.cuppa.ai/team/settings/api/keys) to obtain an API key. Include the API key in the `X-API-KEY` header of your requests as follows:

{% code fullWidth="false" %}

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

{% endcode %}

#### 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 /v1/meta

> Get all metadata

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Metadata","description":"API metadata and available options"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/meta":{"get":{"summary":"Get all metadata","responses":{"200":{"description":"Metadata object","content":{"application/json":{"schema":{"type":"object","properties":{"languages":{"type":"array","items":{"type":"object","required":["name","code"],"properties":{"name":{"type":"string"},"code":{"type":"string"}}}},"regions":{"type":"array","items":{"type":"object","required":["name","code"],"properties":{"name":{"type":"string"},"code":{"type":"string"}}}},"models":{"type":"array","items":{"type":"string"}},"image_models":{"type":"array","items":{"type":"string"}}},"required":["languages","regions","models","image_models"]}}}}},"tags":["Metadata"]}}}}
```

## GET /v1/meta/models

> Get available models

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Metadata","description":"API metadata and available options"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/meta/models":{"get":{"summary":"Get available models","responses":{"200":{"description":"A list of model names","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}}},"tags":["Metadata"]}}}}
```

## Get available image models

> Returns all available image generation models. Models are grouped by provider:\
> \
> \*\*OpenAI models\*\* (require OpenAI API key):\
> \- \`gpt-image-2\`: GPT Image 2, latest state-of-the-art OpenAI image model. Sizes: 1024x1024, 1536x1024, 1024x1536\
> \- \`gpt-image-1.5\`: GPT Image 1.5, fast and high quality. Sizes: 1024x1024, 1536x1024, 1024x1536\
> \- \`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<br>

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Metadata","description":"API metadata and available options"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/meta/image_models":{"get":{"summary":"Get available image models","description":"Returns all available image generation models. Models are grouped by provider:\n\n**OpenAI models** (require OpenAI API key):\n- `gpt-image-2`: GPT Image 2, latest state-of-the-art OpenAI image model. Sizes: 1024x1024, 1536x1024, 1024x1536\n- `gpt-image-1.5`: GPT Image 1.5, fast and high quality. Sizes: 1024x1024, 1536x1024, 1024x1536\n- `gpt-image-1`: GPT Image 1, photorealistic quality. Sizes: 1024x1024, 1536x1024, 1024x1536\n\n**Replicate models** (require Replicate API key):\n- `black-forest-labs/flux-1.1-pro-ultra`: Flux 1.1 Pro Ultra, highest quality Flux model\n- `black-forest-labs/flux-1.1-pro`: Flux 1.1 Pro, high quality with custom dimensions\n- `black-forest-labs/flux-dev`: Flux Dev, fast iteration\n- `black-forest-labs/flux-pro`: Flux Pro, balanced quality and speed\n- `black-forest-labs/flux-schnell`: Flux Schnell, fastest Flux model\n- `stability-ai/stable-diffusion-3`: Stable Diffusion 3\n- `replicate:nano-banana-pro`: Nano Banana Pro, supports 1K/2K/4K resolution output\n- `replicate:imagen-4`: Google Imagen 4 via Replicate\n\n**Google models** (require Google AI API key):\n- `imagen-4.0-generate-001`: Google Imagen 4, native Google API\n","responses":{"200":{"description":"A list of image model names","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}}},"tags":["Metadata"]}}}}
```

## GET /v1/meta/languages

> Get available languages

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Metadata","description":"API metadata and available options"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/meta/languages":{"get":{"summary":"Get available languages","responses":{"200":{"description":"A list of supported languages","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["name","code"],"properties":{"name":{"type":"string"},"code":{"type":"string"}}}}}}}},"tags":["Metadata"]}}}}
```

## GET /v1/meta/regions

> Get available regions

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Metadata","description":"API metadata and available options"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/meta/regions":{"get":{"summary":"Get available regions","responses":{"200":{"description":"A list of supported regions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["name","code"],"properties":{"name":{"type":"string"},"code":{"type":"string"}}}}}}}},"tags":["Metadata"]}}}}
```

## GET /v1/images

> Fetch list of generated images

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Images","description":"AI image generation"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/images":{"get":{"summary":"Fetch list of generated images","parameters":[{"in":"query","name":"limit","schema":{"type":"integer","maximum":50},"description":"Maximum number of images to return (max 50, default 20)"}],"responses":{"200":{"description":"A list of generated images","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","url"],"properties":{"id":{"type":"string"},"url":{"type":"string"}}}}}}}},"tags":["Images"]}}}}
```

## POST /v1/images

> Create an image

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Images","description":"AI image generation"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/images":{"post":{"summary":"Create an image","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","prompt"],"properties":{"model":{"type":"string","description":"The model to use for image generation. Use the `/v1/meta/image_models` endpoint to get the full list.\nOpenAI models use the `size` setting. Replicate/Google models use the `aspect_ratio` setting.\n"},"prompt":{"type":"string","maxLength":1000,"description":"The prompt to use for image generation"},"settings":{"type":"object","description":"Image generation settings. Use `size` for OpenAI models, `aspect_ratio` for Replicate/Google models.","properties":{"size":{"type":"string","enum":["1024x1024","1536x1024","1024x1536"],"default":"1536x1024","description":"Pixel size of the image. Valid for OpenAI models (gpt-image-1, gpt-image-1.5, gpt-image-2) only.\n1024x1024 (square), 1536x1024 (landscape), 1024x1536 (portrait).\n"},"aspect_ratio":{"type":"string","enum":["1:1","16:9","9:16","4:3","3:4","3:2","2:3","5:4","4:5","21:9","9:21"],"default":"16:9","description":"Aspect ratio of the image. Valid for Replicate and Google models.\nNot all ratios are supported by all models. Common options: 16:9 (landscape), 9:16 (portrait/stories), 1:1 (square), 4:3 (standard), 3:2 (classic).\n"},"resolution":{"type":"string","enum":["1K","2K","4K"],"description":"Output resolution. Only valid for `replicate:nano-banana-pro`.\n1K: Fast, good for previews. 2K: Balanced (default). 4K: Highest quality, slower.\n"}}}}}}}},"responses":{"200":{"description":"Successfully generated image","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"}}}}}}},"tags":["Images"]}}}}
```

## GET /v1/contents

> Fetch list of articles

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Contents","description":"Create and manage articles"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Content":{"type":"object","properties":{"id":{"type":"string"},"is_draft":{"type":"boolean","description":"Whether the article is a draft"},"status":{"$ref":"#/components/schemas/TaskStatus"},"title":{"type":"string","nullable":true,"description":"It is null if the article is not generated yet."},"content":{"type":"string","nullable":true,"description":"It is null if the article is not generated yet."},"snippet":{"type":"string","nullable":true},"project_id":{"type":"string","nullable":true,"description":"It is null if the article is not part of a project."},"site_id":{"type":"string","format":"uuid","nullable":true,"description":"The site/brand ID associated with this article. Null if no brand context."},"meta_description":{"type":"string","nullable":true},"featured_images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"alt":{"type":"string","nullable":true}}}},"content_type":{"type":"string","enum":["article"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"target_keyword":{"type":"string"},"language":{"type":"string"},"region":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}},"paths":{"/v1/contents":{"get":{"summary":"Fetch list of articles","parameters":[{"in":"query","name":"page","schema":{"type":"integer","nullable":true},"description":"Page number for pagination"},{"in":"query","name":"lang","schema":{"type":"string","nullable":true},"description":"Filter by language code"},{"in":"query","name":"project","schema":{"type":"string","nullable":true},"description":"Filter by project ID. If not provided, it will return the articles not part of any project. Use `all` to get all articles."},{"in":"query","name":"site","schema":{"type":"string","format":"uuid","nullable":true},"description":"Filter by site/brand ID. Use `GET /v1/sites` to get available site IDs."}],"responses":{"200":{"description":"A list of articles","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Content"}}}}}},"tags":["Contents"]}}}}
```

## Create a new article

> 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\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Contents","description":"Create and manage articles"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"ContentSettings":{"type":"object","required":["language","region"],"properties":{"language":{"type":"string","description":"The language of the article."},"region":{"type":"string","description":"The region of the article."},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"],"default":"seo_optimized","description":"The tone of the article."},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"],"default":"first_person_plural","description":"The point of view of the article."},"article_type":{"type":"string","enum":["general","listicle","review","howto","recipe"],"default":"general","description":"The type of the article."},"fetch_perplexity":{"type":"boolean","default":false,"description":"Whether to use Perplexity for fetching real-time research data. It requires a Perplexity API key."},"include_introduction":{"type":"boolean","default":true,"description":"Whether to include an introduction section in the article."},"include_conclusion":{"type":"boolean","default":true,"description":"Whether to include a conclusion section in the article."},"include_yt_suggestions":{"type":"boolean","default":false,"description":"Whether to include YouTube suggestions in the article."},"generate_faqs":{"type":"boolean","default":false,"description":"Whether to generate a FAQ section in the article."},"generate_meta_description":{"type":"boolean","default":false,"description":"Whether to generate a meta description for the article."},"key_takeaways_position":{"type":"string","default":"none","enum":["top","bottom","none"],"description":"The position of the key takeaways section in the article. Use `none` to disable it."},"include_stock_images":{"type":"boolean","default":false,"description":"Whether to include stock featured images in the article."},"generate_images":{"type":"boolean","default":false,"description":"Whether to generate AI images for the article. Use the `image_settings` object to configure image generation."},"image_settings":{"type":"object","properties":{"model":{"type":"string","default":"gpt-image-1","description":"The image model to use for generation. Use the `/v1/meta/image_models` endpoint to get available image models."},"max_body_images_count":{"type":"integer","minimum":0,"maximum":7,"description":"The maximum number of images to generate in the body. Use `0` to disable body images."},"style_preset":{"type":"string","enum":["vintage","professional","photorealistic","infographic","minimalist_art","comic","watercolor_painting","abstract_art","pop_art","model_3d","line_art"],"nullable":true,"default":"photorealistic","description":"The style preset for the images. Use `custom_style` if you prefer a custom style instead."},"custom_style":{"type":"object","required":["name","description"],"properties":{"name":{"type":"string","description":"The name of the custom style."},"description":{"type":"string","description":"The description of the custom style. This should be a short but detailed description of the style you want to apply to the images."}},"description":"The custom style for the images."}}},"advanced_settings":{"type":"object","properties":{"title_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the title."},"introduction_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the introduction."},"section_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the sections."},"meta_description_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the meta description."}}}}},"ContentStatusResponse":{"type":"object","properties":{"id":{"type":"string"},"is_draft":{"type":"boolean","description":"Whether the article is a draft"},"status":{"$ref":"#/components/schemas/TaskStatus"},"status_extra":{"type":"object","properties":{"error":{"type":"string","nullable":true,"description":"Error message if status is failed"}}}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}},"paths":{"/v1/contents":{"post":{"summary":"Create a new article","description":"Create content using different templates:\n- **article** (default): Full-featured articles with support for listicles, reviews, how-tos. Use `settings.article_type` to specify.\n- **local_news**: Location-focused news articles. Simpler settings, uses `local_news_settings`.\n- **recipe**: Structured recipe content with ingredients, instructions. Uses `recipe_settings`.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target_keyword"],"properties":{"target_keyword":{"type":"string","description":"The target keyword for the content."},"template":{"type":"string","enum":["article","local_news","recipe"],"default":"article","description":"The content template to use:\n- `article`: General articles with full settings (listicle, review, howto, general)\n- `local_news`: Location-focused news content\n- `recipe`: Structured recipe with ingredients and instructions\n"},"site_id":{"type":"string","format":"uuid","nullable":true,"description":"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."},"model":{"type":"string","description":"The AI model to use.","default":"gpt-4o-mini"},"outline":{"type":"array","description":"Optional outline (only for template=article).","items":{"oneOf":[{"type":"object","required":["type","level","title"],"properties":{"type":{"type":"string","enum":["heading"]},"level":{"type":"integer","enum":[2,3,4]},"title":{"type":"string"}}},{"type":"object","required":["type","code"],"properties":{"type":{"type":"string","enum":["custom_code"]},"name":{"type":"string","nullable":true},"code":{"type":"string"}}},{"type":"object","required":["type","code"],"properties":{"type":{"type":"string","enum":["shortcode"]},"name":{"type":"string","nullable":true},"code":{"type":"string"}}}]}},"settings_preset":{"type":"number","description":"Preset ID (only for template=article).","nullable":true},"settings":{"$ref":"#/components/schemas/ContentSettings","description":"Article settings (only for template=article)."},"local_news_settings":{"type":"object","description":"Settings for template=local_news.","properties":{"target_audience":{"type":"string","maxLength":500,"description":"Target audience for the local news article."},"extra_prompt":{"type":"string","maxLength":50000,"description":"Additional AI instructions."}}},"recipe_settings":{"type":"object","description":"Settings for template=recipe.","properties":{"recipe_template":{"type":"string","enum":["original","card","minimal","modern","elegant","magazine","vintage","compact"],"default":"modern","description":"Display template for the recipe."}}},"use_serp":{"type":"boolean","description":"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_draft":{"type":"boolean","description":"Whether to save as draft (won't generate immediately)","default":false}}}}}},"responses":{"200":{"description":"Content created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentStatusResponse"}}}}},"tags":["Contents"]}}}}
```

## GET /v1/contents/{id}

> Get an article by ID

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Contents","description":"Create and manage articles"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Content":{"type":"object","properties":{"id":{"type":"string"},"is_draft":{"type":"boolean","description":"Whether the article is a draft"},"status":{"$ref":"#/components/schemas/TaskStatus"},"title":{"type":"string","nullable":true,"description":"It is null if the article is not generated yet."},"content":{"type":"string","nullable":true,"description":"It is null if the article is not generated yet."},"snippet":{"type":"string","nullable":true},"project_id":{"type":"string","nullable":true,"description":"It is null if the article is not part of a project."},"site_id":{"type":"string","format":"uuid","nullable":true,"description":"The site/brand ID associated with this article. Null if no brand context."},"meta_description":{"type":"string","nullable":true},"featured_images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"alt":{"type":"string","nullable":true}}}},"content_type":{"type":"string","enum":["article"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"target_keyword":{"type":"string"},"language":{"type":"string"},"region":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}},"paths":{"/v1/contents/{id}":{"get":{"summary":"Get an article by ID","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The ID of the article"}],"responses":{"200":{"description":"The article object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Content"}}}}},"tags":["Contents"]}}}}
```

## GET /v1/contents/{id}/status

> Get the current status of an article

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Contents","description":"Create and manage articles"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"ContentStatusResponse":{"type":"object","properties":{"id":{"type":"string"},"is_draft":{"type":"boolean","description":"Whether the article is a draft"},"status":{"$ref":"#/components/schemas/TaskStatus"},"status_extra":{"type":"object","properties":{"error":{"type":"string","nullable":true,"description":"Error message if status is failed"}}}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}},"paths":{"/v1/contents/{id}/status":{"get":{"summary":"Get the current status of an article","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The ID of the article"}],"responses":{"200":{"description":"The status of the article","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentStatusResponse"}}}}},"tags":["Contents"]}}}}
```

## GET /v1/projects

> Fetch list of projects

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Bulk content generation projects"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/projects":{"get":{"summary":"Fetch list of projects","responses":{"200":{"description":"A list of projects","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}}}},"tags":["Projects"]}}}}
```

## POST /v1/projects

> Create a new project

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Bulk content generation projects"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"ContentSettings":{"type":"object","required":["language","region"],"properties":{"language":{"type":"string","description":"The language of the article."},"region":{"type":"string","description":"The region of the article."},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"],"default":"seo_optimized","description":"The tone of the article."},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"],"default":"first_person_plural","description":"The point of view of the article."},"article_type":{"type":"string","enum":["general","listicle","review","howto","recipe"],"default":"general","description":"The type of the article."},"fetch_perplexity":{"type":"boolean","default":false,"description":"Whether to use Perplexity for fetching real-time research data. It requires a Perplexity API key."},"include_introduction":{"type":"boolean","default":true,"description":"Whether to include an introduction section in the article."},"include_conclusion":{"type":"boolean","default":true,"description":"Whether to include a conclusion section in the article."},"include_yt_suggestions":{"type":"boolean","default":false,"description":"Whether to include YouTube suggestions in the article."},"generate_faqs":{"type":"boolean","default":false,"description":"Whether to generate a FAQ section in the article."},"generate_meta_description":{"type":"boolean","default":false,"description":"Whether to generate a meta description for the article."},"key_takeaways_position":{"type":"string","default":"none","enum":["top","bottom","none"],"description":"The position of the key takeaways section in the article. Use `none` to disable it."},"include_stock_images":{"type":"boolean","default":false,"description":"Whether to include stock featured images in the article."},"generate_images":{"type":"boolean","default":false,"description":"Whether to generate AI images for the article. Use the `image_settings` object to configure image generation."},"image_settings":{"type":"object","properties":{"model":{"type":"string","default":"gpt-image-1","description":"The image model to use for generation. Use the `/v1/meta/image_models` endpoint to get available image models."},"max_body_images_count":{"type":"integer","minimum":0,"maximum":7,"description":"The maximum number of images to generate in the body. Use `0` to disable body images."},"style_preset":{"type":"string","enum":["vintage","professional","photorealistic","infographic","minimalist_art","comic","watercolor_painting","abstract_art","pop_art","model_3d","line_art"],"nullable":true,"default":"photorealistic","description":"The style preset for the images. Use `custom_style` if you prefer a custom style instead."},"custom_style":{"type":"object","required":["name","description"],"properties":{"name":{"type":"string","description":"The name of the custom style."},"description":{"type":"string","description":"The description of the custom style. This should be a short but detailed description of the style you want to apply to the images."}},"description":"The custom style for the images."}}},"advanced_settings":{"type":"object","properties":{"title_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the title."},"introduction_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the introduction."},"section_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the sections."},"meta_description_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the meta description."}}}}},"Project":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"articles":{"type":"object","description":"A record of article IDs and their corresponding task status","additionalProperties":{"$ref":"#/components/schemas/TaskStatus"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}},"paths":{"/v1/projects":{"post":{"summary":"Create a new project","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_name":{"type":"string","description":"Name of the project","maxLength":100},"site_id":{"type":"string","format":"uuid","nullable":true,"description":"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."},"model":{"type":"string","description":"The model to use for the article. Use the `/v1/meta/models` endpoint to get available models.","default":"gpt-4o-mini"},"common_settings_preset":{"type":"number","description":"The settings preset to use for the project. Use the `common_settings` object to override specific settings. Go to your [presets](https://app.cuppa.ai/presets/my) to create a preset.","nullable":true},"common_settings":{"$ref":"#/components/schemas/ContentSettings","description":"The common settings to use for the project. Use the `common_settings_preset` property to specify a preset."},"target_keywords":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":600,"description":"The target keywords to generate content for."}},"required":["project_name","target_keywords"]}}}},"responses":{"200":{"description":"Project created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}}},"tags":["Projects"]}}}}
```

## GET /v1/projects/{id}

> Get a project by ID

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Bulk content generation projects"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Project":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"articles":{"type":"object","description":"A record of article IDs and their corresponding task status","additionalProperties":{"$ref":"#/components/schemas/TaskStatus"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}},"paths":{"/v1/projects/{id}":{"get":{"summary":"Get a project by ID","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The ID of the project"}],"responses":{"200":{"description":"The project object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}}},"tags":["Projects"]}}}}
```

## The Error object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}}}}}}}}
```

## The TaskStatus object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}}}
```

## The Content object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"Content":{"type":"object","properties":{"id":{"type":"string"},"is_draft":{"type":"boolean","description":"Whether the article is a draft"},"status":{"$ref":"#/components/schemas/TaskStatus"},"title":{"type":"string","nullable":true,"description":"It is null if the article is not generated yet."},"content":{"type":"string","nullable":true,"description":"It is null if the article is not generated yet."},"snippet":{"type":"string","nullable":true},"project_id":{"type":"string","nullable":true,"description":"It is null if the article is not part of a project."},"site_id":{"type":"string","format":"uuid","nullable":true,"description":"The site/brand ID associated with this article. Null if no brand context."},"meta_description":{"type":"string","nullable":true},"featured_images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"alt":{"type":"string","nullable":true}}}},"content_type":{"type":"string","enum":["article"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"target_keyword":{"type":"string"},"language":{"type":"string"},"region":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}}}
```

## The ContentStatusResponse object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"ContentStatusResponse":{"type":"object","properties":{"id":{"type":"string"},"is_draft":{"type":"boolean","description":"Whether the article is a draft"},"status":{"$ref":"#/components/schemas/TaskStatus"},"status_extra":{"type":"object","properties":{"error":{"type":"string","nullable":true,"description":"Error message if status is failed"}}}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}}}
```

## The ContentSettings object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"ContentSettings":{"type":"object","required":["language","region"],"properties":{"language":{"type":"string","description":"The language of the article."},"region":{"type":"string","description":"The region of the article."},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"],"default":"seo_optimized","description":"The tone of the article."},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"],"default":"first_person_plural","description":"The point of view of the article."},"article_type":{"type":"string","enum":["general","listicle","review","howto","recipe"],"default":"general","description":"The type of the article."},"fetch_perplexity":{"type":"boolean","default":false,"description":"Whether to use Perplexity for fetching real-time research data. It requires a Perplexity API key."},"include_introduction":{"type":"boolean","default":true,"description":"Whether to include an introduction section in the article."},"include_conclusion":{"type":"boolean","default":true,"description":"Whether to include a conclusion section in the article."},"include_yt_suggestions":{"type":"boolean","default":false,"description":"Whether to include YouTube suggestions in the article."},"generate_faqs":{"type":"boolean","default":false,"description":"Whether to generate a FAQ section in the article."},"generate_meta_description":{"type":"boolean","default":false,"description":"Whether to generate a meta description for the article."},"key_takeaways_position":{"type":"string","default":"none","enum":["top","bottom","none"],"description":"The position of the key takeaways section in the article. Use `none` to disable it."},"include_stock_images":{"type":"boolean","default":false,"description":"Whether to include stock featured images in the article."},"generate_images":{"type":"boolean","default":false,"description":"Whether to generate AI images for the article. Use the `image_settings` object to configure image generation."},"image_settings":{"type":"object","properties":{"model":{"type":"string","default":"gpt-image-1","description":"The image model to use for generation. Use the `/v1/meta/image_models` endpoint to get available image models."},"max_body_images_count":{"type":"integer","minimum":0,"maximum":7,"description":"The maximum number of images to generate in the body. Use `0` to disable body images."},"style_preset":{"type":"string","enum":["vintage","professional","photorealistic","infographic","minimalist_art","comic","watercolor_painting","abstract_art","pop_art","model_3d","line_art"],"nullable":true,"default":"photorealistic","description":"The style preset for the images. Use `custom_style` if you prefer a custom style instead."},"custom_style":{"type":"object","required":["name","description"],"properties":{"name":{"type":"string","description":"The name of the custom style."},"description":{"type":"string","description":"The description of the custom style. This should be a short but detailed description of the style you want to apply to the images."}},"description":"The custom style for the images."}}},"advanced_settings":{"type":"object","properties":{"title_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the title."},"introduction_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the introduction."},"section_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the sections."},"meta_description_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the meta description."}}}}}}}}
```

## The Project object

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"Project":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"articles":{"type":"object","description":"A record of article IDs and their corresponding task status","additionalProperties":{"$ref":"#/components/schemas/TaskStatus"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.cuppa.ai/rest-api/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.