# Contents
Create and manage articles
## 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\`.
```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"]}}}}
```
## Import article from URL
> Import an existing article by URL. Scrapes the page and creates a Cuppa 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"}}},"paths":{"/v1/contents/import":{"post":{"summary":"Import article from URL","description":"Import an existing article by URL. Scrapes the page and creates a Cuppa article.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"URL to import"},"language":{"type":"string","default":"en","description":"Language code"},"site_id":{"type":"string","format":"uuid","description":"Site to associate with"}}}}}},"responses":{"201":{"description":"Article imported","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Created article ID"},"status":{"type":"string","enum":["imported"]},"url":{"type":"string","description":"Original URL"}}}}}}},"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"]}}}}
```
## Update an article
> Update title, HTML content, meta description, or target keyword of an existing article. At least one field is required. Content updates persist to the article body and are reflected in subsequent GET requests.
```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}":{"patch":{"summary":"Update an article","description":"Update title, HTML content, meta description, or target keyword of an existing article. At least one field is required. Content updates persist to the article body and are reflected in subsequent GET requests.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The article ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Article title"},"content":{"type":"string","description":"HTML content"},"meta_description":{"type":"string","description":"SEO meta description"},"target_keyword":{"type":"string","description":"Target keyword"}}}}}},"responses":{"200":{"description":"The updated article","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.
```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.
```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.
```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.
```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"]}}}}
```
## Publish article to CMS platform
> Push an article to an external CMS (Ghost, Webflow, Contentful, Sanity, Airtable).\
> The integration must be configured in team settings first.\
> Requires Power plan or higher.
```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}/publish":{"post":{"summary":"Publish article to CMS platform","description":"Push an article to an external CMS (Ghost, Webflow, Contentful, Sanity, Airtable).\nThe integration must be configured in team settings first.\nRequires Power plan or higher.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The article ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","enum":["ghost","webflow","contentful","sanity","airtable","shopify"]},"options":{"type":"object","properties":{"status":{"type":"string","enum":["publish","draft"],"default":"publish"},"categories":{"type":"array","items":{"type":"string"},"description":"WordPress/Ghost categories"},"tags":{"type":"array","items":{"type":"string"},"description":"WordPress/Ghost tags"},"collection_id":{"type":"string","description":"Webflow collection ID"}}}}}}}},"responses":{"200":{"description":"Article published","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"platform":{"type":"string"},"external_id":{"type":"string","nullable":true},"external_url":{"type":"string","nullable":true},"error":{"type":"string","nullable":true}}}}}}},"tags":["Contents"]}}}}
```
---
# 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/contents.md?ask=
```
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.