# Models ## 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 Page object ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"Page":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","generating","complete","error"]},"page_type":{"type":"string","enum":["landing_page","product_page","comparison","alternatives"]},"sections":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string","nullable":true},"content":{"type":"string","nullable":true}}}},"meta":{"type":"object","description":"Page metadata (target_keyword, meta_title, meta_description, etc.)"},"site_id":{"type":"string","format":"uuid"},"team_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true},"schema_markup":{"type":"array","items":{"type":"object"},"description":"JSON-LD schema objects (WebPage, FAQPage, Product). Present on GET /v1/pages/{id}."}}}}}} ``` ## 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"]}}}} ``` ## 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 ContentStrategySettings object ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"ContentStrategySettings":{"type":"object","description":"Content strategy settings for a site","properties":{"article_defaults":{"type":"object","properties":{"model":{"type":"string","description":"AI model for article generation"},"generate_meta_description":{"type":"boolean"},"generate_faq":{"type":"boolean"},"include_introduction":{"type":"boolean"},"include_conclusion":{"type":"boolean"},"generate_ai_images":{"type":"boolean"},"target_length":{"type":"string","enum":["short","medium","long","comprehensive"]},"extra_prompt":{"type":"string","nullable":true}}},"social_publishing":{"type":"object","properties":{"enabled":{"type":"boolean"},"auto_post_on_publish":{"type":"boolean"},"default_platforms":{"type":"array","items":{"type":"string"}},"default_tone":{"type":"string","enum":["professional","casual","humorous","educational","inspirational"]},"include_article_link":{"type":"boolean"},"include_hashtags":{"type":"boolean"},"max_hashtags":{"type":"integer"},"schedule_delay_minutes":{"type":"integer"},"generate_images":{"type":"boolean"}}},"newsletter":{"type":"object","properties":{"enabled":{"type":"boolean"},"cadence":{"type":"string","enum":["weekly","biweekly","monthly","none"]},"include_recent_articles":{"type":"boolean"},"max_articles_per_newsletter":{"type":"integer"},"send_day":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"]},"send_hour":{"type":"integer"}}},"automation":{"type":"object","properties":{"planner_paused":{"type":"boolean"},"auto_schedule_from_clusters":{"type":"boolean"},"default_posts_per_week":{"type":"integer"},"preferred_publish_days":{"type":"array","items":{"type":"string"}},"preferred_publish_hour":{"type":"integer"},"auto_generate_social_on_publish":{"type":"boolean"},"auto_add_to_newsletter":{"type":"boolean"}}}}}}}} ``` ## 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 PlannerEvent object ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"PlannerEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"team_id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string"},"description":{"type":"string","nullable":true},"event_date":{"type":"string","format":"date"},"event_type":{"type":"string","enum":["holiday","cultural","industry","custom","product_launch","seasonal"]},"recurrence":{"type":"string","enum":["none","annual","monthly","weekly"]},"source":{"type":"string","enum":["user","system","nager"]},"country_code":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}} ``` ## 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 SocialPostRecord object ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"SocialPostRecord":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string"},"content":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"image_url":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","scheduled","published","failed"]},"scheduled_at":{"type":"string","format":"date-time","nullable":true},"published_at":{"type":"string","format":"date-time","nullable":true},"article_id":{"type":"string","format":"uuid","nullable":true},"late_post_id":{"type":"string","nullable":true},"error_message":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"post_type":{"type":"string","nullable":true},"voice_mode":{"type":"string","nullable":true},"site_id":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}} ``` ## The MoodBoard object ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"MoodBoard":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"site_id":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}} ``` ## 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"}}}}}}}} ``` ## The TemplateListItem object ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"TemplateListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"site_id":{"type":"string","format":"uuid","nullable":true},"variables":{"type":"object","additionalProperties":{"type":"string"}},"include_faq":{"type":"boolean"},"include_key_takeaways":{"type":"boolean"},"include_ai_images":{"type":"boolean"},"enable_knowledge":{"type":"boolean"},"enable_perplexity":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}} ``` ## The TemplateDetail object ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"TemplateDetail":{"allOf":[{"$ref":"#/components/schemas/TemplateListItem"},{"type":"object","properties":{"system_prompt":{"type":"string"},"user_prompt":{"type":"string"},"ideal_output":{"type":"string","nullable":true},"knowledge_sources":{"type":"array","items":{"type":"integer"}},"include_toc":{"type":"boolean"},"enable_serp":{"type":"boolean"},"ai_image_style":{"type":"string","nullable":true},"ai_image_model":{"type":"string","nullable":true},"ai_image_count_body":{"type":"integer"}}}]},"TemplateListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"site_id":{"type":"string","format":"uuid","nullable":true},"variables":{"type":"object","additionalProperties":{"type":"string"}},"include_faq":{"type":"boolean"},"include_key_takeaways":{"type":"boolean"},"include_ai_images":{"type":"boolean"},"enable_knowledge":{"type":"boolean"},"enable_perplexity":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}} ``` ## The NotebookEntry object ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"NotebookEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"content":{"type":"string"},"meeting_date":{"type":"string","format":"date","nullable":true},"source":{"type":"string"},"processing_status":{"type":"string","enum":["pending","processing","completed","failed"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}} ``` ## The Agent object ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"agent_type":{"type":"string","enum":["local_news","content_gap","trend_research","programmatic_seo"]},"site_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","running","error"]},"schedule":{"type":"string","enum":["weekly","biweekly","monthly","manual"]},"run_count":{"type":"integer"},"last_run_at":{"type":"string","format":"date-time","nullable":true},"next_run_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}}}}} ``` ## The AgentDetail object ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"AgentDetail":{"allOf":[{"$ref":"#/components/schemas/Agent"},{"type":"object","properties":{"config":{"type":"object","description":"Agent-type-specific configuration"},"sources":{"type":"array","items":{"type":"object"},"description":"Data sources configuration"},"latest_snapshot":{"type":"object","nullable":true,"description":"Most recent agent run snapshot with crawl stats and extracted data"},"latest_brief":{"type":"object","nullable":true,"description":"Most recent research brief with content ideas and keywords"}}}]},"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"agent_type":{"type":"string","enum":["local_news","content_gap","trend_research","programmatic_seo"]},"site_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","running","error"]},"schedule":{"type":"string","enum":["weekly","biweekly","monthly","manual"]},"run_count":{"type":"integer"},"last_run_at":{"type":"string","format":"date-time","nullable":true},"next_run_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}}}}} ``` ## The PerformanceOverview object ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"PerformanceOverview":{"type":"object","properties":{"kpis":{"type":"object","properties":{"organicClicks":{"type":"object","properties":{"value":{"type":"integer"},"pctChange":{"type":"integer"}}},"organicImpressions":{"type":"object","properties":{"value":{"type":"integer"},"pctChange":{"type":"integer"}}},"ctr":{"type":"object","properties":{"value":{"type":"number"},"pctChange":{"type":"integer"}}},"aiCitations":{"type":"object","properties":{"value":{"type":"integer"}}},"socialReach":{"type":"object","properties":{"value":{"type":"integer"},"pctChange":{"type":"integer"}}},"sessions":{"type":"object","properties":{"value":{"type":"integer"}}},"avgContentGrade":{"type":"object","properties":{"value":{"type":"number"}}}}},"visibilityScore":{"type":"object","nullable":true,"properties":{"score":{"type":"number"},"organicScore":{"type":"number"},"aiVisibilityScore":{"type":"number"},"contentQualityScore":{"type":"number"},"socialScore":{"type":"number"},"change":{"type":"number"}}},"quickWins":{"type":"object","properties":{"pagesLosingTraffic":{"type":"integer"},"pagesNotCitedByAi":{"type":"integer"},"pagesAgingOut":{"type":"integer"},"strikingDistanceKeywords":{"type":"integer"}}}}}}}} ``` ## The ContentHealth object ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"ContentHealth":{"type":"object","properties":{"topPages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"clicks":{"type":"integer"},"impressions":{"type":"integer"},"position":{"type":"number"}}}},"contentDecay":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"currentClicks":{"type":"integer"},"previousClicks":{"type":"integer"},"dropPct":{"type":"integer"}}}},"strikingDistance":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"page_url":{"type":"string"},"position":{"type":"number"},"impressions":{"type":"integer"},"clicks":{"type":"integer"}}}},"cannibalization":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"pages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"clicks":{"type":"integer"},"impressions":{"type":"integer"},"position":{"type":"number"}}}}}}}}}}}} ``` ## The AiVisibility object ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"AiVisibility":{"type":"object","properties":{"overview":{"type":"object","properties":{"totalMentions":{"type":"integer"},"chatgptMentions":{"type":"integer"},"googleAioMentions":{"type":"integer"},"uniquePrompts":{"type":"integer"}}},"topPrompts":{"type":"array","items":{"type":"object","properties":{"prompt":{"type":"string"},"llmSources":{"type":"array","items":{"type":"string"}},"pageUrl":{"type":"string","nullable":true},"firstSeen":{"type":"string"}}}},"topCitedPages":{"type":"array","items":{"type":"object","properties":{"pageUrl":{"type":"string"},"citations":{"type":"integer"}}}},"citationGaps":{"type":"array","items":{"type":"object","properties":{"prompt":{"type":"string"},"competitorDomain":{"type":"string"},"competitorUrl":{"type":"string","nullable":true},"yourCoverage":{"type":"boolean"}}}}}}}}} ``` ## The Backlinks object ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"Backlinks":{"type":"object","properties":{"connected":{"type":"boolean"},"overview":{"type":"object","properties":{"domainRating":{"type":"number","nullable":true},"ahrefsRank":{"type":"integer","nullable":true},"backlinksLive":{"type":"integer","nullable":true},"backlinksAllTime":{"type":"integer","nullable":true},"refdomainsLive":{"type":"integer","nullable":true},"refdomainsAllTime":{"type":"integer","nullable":true}}},"referringDomains":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"domainRating":{"type":"number","nullable":true},"backlinks":{"type":"integer"},"firstSeen":{"type":"string","nullable":true},"lastSeen":{"type":"string","nullable":true}}}}}}}}} ``` ## The Newsletter object ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"Newsletter":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"week_start":{"type":"string","format":"date"},"status":{"type":"string"},"subject":{"type":"string","nullable":true},"article_ids":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"}},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}} ``` ## The NewsletterDetail object ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"components":{"schemas":{"NewsletterDetail":{"allOf":[{"$ref":"#/components/schemas/Newsletter"},{"type":"object","properties":{"content":{"type":"object","description":"Structured newsletter content (intro, article summaries, outro)"},"html_content":{"type":"string","nullable":true,"description":"Full HTML email content"}}}]},"Newsletter":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"week_start":{"type":"string","format":"date"},"status":{"type":"string"},"subject":{"type":"string","nullable":true},"article_ids":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"}},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}} ``` --- # 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/models.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.