{
  "openapi": "3.1.0",
  "info": {
    "title": "Cuppa API",
    "version": "1.0.0",
    "description": "Use the Cuppa API to generate content and images using AI. The capabilities of the API are defined in the next sections.\n\n### Interfaces\n\nThe Cuppa API can be accessed three ways:\n\n- **REST API** (this spec): Direct HTTP calls for custom integrations, automation platforms (Zapier, Make), and ChatGPT Actions.\n- **CLI**: `npm install -g @cuppa-ai/cli` for terminal workflows, AI agents with shell access (Claude Code, Cursor), and scripting. Commands include high-level workflows like `cuppa generate`, `cuppa optimize`, `cuppa campaign`, and `cuppa seo`.\n- **MCP Server**: `npx @cuppa-ai/mcp-server` for AI editors (Cursor, Claude Desktop, Windsurf). 181 tools auto-discovered by MCP-compatible clients.\n\nAll three use the same API key and write to the same database. Content created via any interface is visible in the Cuppa web app.\n\n### Authentication\nTo 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:\n\n```\ncurl -X GET \"https://api.cuppa.ai/v1/meta\" \\\n  -H \"accept: application/json\" \\\n  -H \"X-API-KEY: YOUR_API_KEY\"\n```\n\nFor the CLI, authenticate with `cuppa auth login` or set the `CUPPA_API_KEY` environment variable.\n\n### Rate Limiting\nThe API has rate limits in place to ensure fair usage.\n\n### Error Handling\nThe 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."
  },
  "servers": [
    {
      "url": "https://api.cuppa.ai"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Metadata",
      "description": "API metadata and available options"
    },
    {
      "name": "Contents",
      "description": "Create and manage articles"
    },
    {
      "name": "Briefs",
      "description": "Parse content briefs into structured article parameters"
    },
    {
      "name": "Projects",
      "description": "Bulk content generation projects"
    },
    {
      "name": "Sites",
      "description": "Site/brand management and Brand DNA"
    },
    {
      "name": "Images",
      "description": "AI image generation"
    },
    {
      "name": "Presets",
      "description": "Content generation presets"
    },
    {
      "name": "Knowledge",
      "description": "Knowledge sources for RAG"
    },
    {
      "name": "Skills",
      "description": "Brand Skills (procedural playbooks) imported from GitHub, zip, or created manually"
    },
    {
      "name": "Clusters",
      "description": "Keyword cluster management"
    },
    {
      "name": "Planner",
      "description": "Content planning and scheduling"
    },
    {
      "name": "Chat",
      "description": "Chat with Cuppa AI research agent"
    },
    {
      "name": "Social",
      "description": "Social media content generation and publishing"
    },
    {
      "name": "Links",
      "description": "Link Engine for internal linking"
    },
    {
      "name": "Research",
      "description": "Keyword and competitor research"
    },
    {
      "name": "Brand Intel",
      "description": "Social listen, public reviews, competitor ads, people and creator find"
    },
    {
      "name": "Templates",
      "description": "Custom content templates (Workbench)"
    },
    {
      "name": "Agents",
      "description": "Research agents for automated content research"
    },
    {
      "name": "Brand Notebook",
      "description": "Client notes and meeting transcripts"
    },
    {
      "name": "Video",
      "description": "AI video generation (scripts, generation, status)"
    },
    {
      "name": "Mood Board",
      "description": "Visual inspiration mood boards"
    },
    {
      "name": "Tracker",
      "description": "DataForSEO rank tracker - domain keyword rankings and real per-URL indexation (PBN, feature-flag gated)"
    },
    {
      "name": "Integrations",
      "description": "Trigger Cuppa actions through connected integrations (Slack commands + approvals)"
    },
    {
      "name": "Automations",
      "description": "Brand Room scheduled automations (one per chat, max 5 per site)"
    },
    {
      "name": "Notifications",
      "description": "Team email and Slack notification preferences and send-now alerts"
    }
  ],
  "webhooks": {
    "contentGenerationCompleted": {
      "post": {
        "summary": "Content Generation Completed",
        "description": "This webhook is triggered when the content generation is completed. It provides the generated content and its status.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event": {
                    "type": "string",
                    "enum": [
                      "content.generation_completed"
                    ]
                  },
                  "data": {
                    "$ref": "#/components/schemas/Content"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledge receipt of the webhook"
          }
        }
      }
    },
    "contentGenerationFailed": {
      "post": {
        "summary": "Content Generation Failed",
        "description": "This webhook is triggered when the content generation fails. It provides the error details.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event": {
                    "type": "string",
                    "enum": [
                      "content.generation_failed"
                    ]
                  },
                  "data": {
                    "$ref": "#/components/schemas/ContentStatusResponse"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledge receipt of the webhook"
          }
        }
      }
    },
    "projectExportCompleted": {
      "post": {
        "summary": "Project Export Completed",
        "description": "This webhook is triggered when a bulk export to an external system (e.g., Airtable) completes.\nIt provides details about the export including the number of articles exported and any errors.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event": {
                    "type": "string",
                    "enum": [
                      "project.export_completed"
                    ]
                  },
                  "data": {
                    "type": "object",
                    "properties": {
                      "project_id": {
                        "type": "string",
                        "description": "The ID of the exported project"
                      },
                      "destination": {
                        "type": "string",
                        "enum": [
                          "airtable"
                        ],
                        "description": "The export destination"
                      },
                      "total_articles": {
                        "type": "integer",
                        "description": "Total number of articles that were queued for export"
                      },
                      "exported_articles": {
                        "type": "integer",
                        "description": "Number of articles successfully exported"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "complete",
                          "failed"
                        ],
                        "description": "Overall status of the export"
                      },
                      "errors": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "List of error messages if any"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledge receipt of the webhook"
          }
        }
      }
    }
  },
  "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"
        ]
      }
    },
    "/v1/meta/models": {
      "get": {
        "summary": "Get available models",
        "description": "Returns all available text generation model IDs. Current flagship IDs include\n`gpt-6.2-astra`, `gpt-6.2-sol`, `gpt-6-luna`, `claude-opus-5-5`, `claude-sonnet-5-5`,\n`claude-fable-5-2`, `grok-4.7`, and `gemini-3.5-flash`. Use this list as the source of truth.\n",
        "responses": {
          "200": {
            "description": "A list of model names",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "gpt-6.2-astra",
                    "gpt-6.2-sol",
                    "gpt-6-astra",
                    "gpt-6-sol",
                    "gpt-6-luna",
                    "claude-opus-5-5",
                    "claude-sonnet-5-5",
                    "claude-fable-5-2",
                    "claude-fable-5-1",
                    "grok-4.7",
                    "gemini-3.5-flash"
                  ]
                }
              }
            }
          }
        },
        "tags": [
          "Metadata"
        ]
      }
    },
    "/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\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:nano-banana-2`: Nano Banana 2\n- `replicate:imagen-4`: Google Imagen 4 via Replicate\n\n**xAI models** (require xAI API key):\n- `grok-imagine-image-2.0`: Grok Imagine 2, current Quality Mode. Strong instruction following, typography, and layout. Uses the `aspect_ratio` setting. $0.04/image.\n\n**Retired models**: `gpt-image-1`, `gpt-image-1.5`, `grok-imagine-image-quality` and `imagen-4.0-generate-001` are still accepted. The two OpenAI ids run on `gpt-image-2`, and the others on `grok-imagine-image-2.0` and Google `gemini-nano-banana-2.1`.\n",
        "responses": {
          "200": {
            "description": "A list of image model names",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "gpt-image-2",
                    "black-forest-labs/flux-1.1-pro-ultra",
                    "black-forest-labs/flux-1.1-pro",
                    "black-forest-labs/flux-dev",
                    "black-forest-labs/flux-pro",
                    "black-forest-labs/flux-schnell",
                    "stability-ai/stable-diffusion-3",
                    "replicate:nano-banana-pro",
                    "replicate:nano-banana-2",
                    "replicate:imagen-4",
                    "grok-imagine-image-2.0"
                  ]
                }
              }
            }
          }
        },
        "tags": [
          "Metadata"
        ]
      }
    },
    "/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"
        ]
      }
    },
    "/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"
        ]
      }
    },
    "/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": {
        "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, and xAI Grok Imagine models use the `aspect_ratio` setting.\n",
                    "example": "gpt-image-2"
                  },
                  "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, and xAI Grok Imagine 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, Google, and xAI Grok Imagine 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"
        ]
      }
    },
    "/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"
        ]
      },
      "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. Examples - gpt-6.2-sol, gpt-6-luna, gpt-6.2-astra, claude-opus-5-5, claude-fable-5-2, grok-4.7, gemini-3.5-flash. Use `/v1/meta/models` for the full list.",
                    "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 any plan (Solo 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"
        ]
      }
    },
    "/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"
        ]
      }
    },
    "/v1/briefs": {
      "post": {
        "summary": "Parse a content brief",
        "description": "Parse a content brief (any format: formal document, bullet points, or narrative) into structured article generation parameters.\nReturns extracted outline, keywords, tone, audience, content gaps, and instructions that can be used with POST /v1/contents.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "content"
                ],
                "properties": {
                  "content": {
                    "type": "string",
                    "description": "The raw content brief text to parse (minimum 50 characters)"
                  },
                  "model": {
                    "type": "string",
                    "description": "AI model for parsing (e.g. gpt-6-sol, gpt-6-luna, claude-opus-5-5, grok-4.7). Defaults to team default."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Brief parsed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string",
                      "description": "Target article title or H1"
                    },
                    "target_keyword": {
                      "type": "string",
                      "description": "Primary target keyword"
                    },
                    "secondary_keywords": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Secondary keywords"
                    },
                    "word_count": {
                      "type": "integer",
                      "description": "Target word count"
                    },
                    "tone": {
                      "type": "string",
                      "description": "Tone/style directive"
                    },
                    "target_audience": {
                      "type": "string",
                      "description": "Target audience description"
                    },
                    "article_type": {
                      "type": "string",
                      "enum": [
                        "general",
                        "listicle",
                        "review",
                        "howto"
                      ]
                    },
                    "outline": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "level": {
                            "type": "integer",
                            "description": "Heading level (2 for H2, 3 for H3)"
                          },
                          "title": {
                            "type": "string",
                            "description": "Heading text"
                          },
                          "instructions": {
                            "type": "string",
                            "description": "Section-specific instructions"
                          }
                        }
                      }
                    },
                    "content_gaps": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Required differentiation points"
                    },
                    "paa_questions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "People Also Ask questions"
                    },
                    "extra_instructions": {
                      "type": "string",
                      "description": "Catch-all for other editorial rules and requirements"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Briefs"
        ]
      }
    },
    "/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"
        ]
      },
      "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"
        ]
      }
    },
    "/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"
        ]
      }
    },
    "/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 any plan (Solo 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"
        ]
      },
      "post": {
        "summary": "Trigger grading for an article",
        "description": "Analyzes the article and generates a content grade. Requires any plan (Solo 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"
        ]
      }
    },
    "/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 any plan (Solo 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"
        ]
      },
      "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 any plan (Solo 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"
        ]
      }
    },
    "/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 any plan (Solo 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"
        ]
      }
    },
    "/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": {
        "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. Examples - gpt-6.2-sol, gpt-6-luna, gpt-6.2-astra, claude-opus-5-5, grok-4.7. Use `/v1/meta/models` for the full list.",
                    "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"
        ]
      }
    },
    "/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"
        ]
      }
    },
    "/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"
        ]
      }
    },
    "/v1/sites": {
      "get": {
        "summary": "List all sites/brands",
        "description": "Returns sites (brands) for your team. For large teams, use `domain` for exact\nlookup (e.g. `?domain=homerocketrealty.com`) or `search` to filter by domain\nsubstring. Pagination uses `page` + `limit` (default 50, max 500). Response\nheaders include `X-Total-Count`, `X-Page`, `X-Limit`, and `X-Has-More`.\n",
        "parameters": [
          {
            "in": "query",
            "name": "page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "Page number for pagination"
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 50
            },
            "description": "Results per page (max 500)"
          },
          {
            "in": "query",
            "name": "domain",
            "schema": {
              "type": "string"
            },
            "description": "Exact domain lookup (e.g. homerocketrealty.com). Returns 0 or 1 site."
          },
          {
            "in": "query",
            "name": "search",
            "schema": {
              "type": "string"
            },
            "description": "Case-insensitive domain substring search"
          },
          {
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "inactive",
                "all"
              ],
              "default": "all"
            },
            "description": "Filter by site status"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of sites",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Site"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Sites"
        ]
      },
      "post": {
        "summary": "Create a new site/brand",
        "description": "Create a new site/brand with full Brand DNA onboarding. The brand analysis (company info, competitors, voice, visual style) is automatically queued and completes in 1-2 minutes.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "description": "The domain of the site (e.g., \"example.com\")"
                  },
                  "name": {
                    "type": "string",
                    "description": "Optional display name for the brand"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Site created and Brand DNA queued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "domain": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "queued"
                      ]
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Site already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "tags": [
          "Sites"
        ]
      }
    },
    "/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"
        ]
      }
    },
    "/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"
        ]
      }
    },
    "/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": {
        "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"
        ]
      }
    },
    "/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": {
        "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"
        ]
      },
      "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"
        ]
      }
    },
    "/v1/knowledge": {
      "get": {
        "summary": "List knowledge sources",
        "description": "Returns a list of knowledge sources (RAG documents). Requires any plan (Solo 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"
        ]
      },
      "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"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Attach this knowledge source to a brand/site"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Knowledge source created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeSource"
                }
              }
            }
          }
        },
        "tags": [
          "Knowledge"
        ]
      }
    },
    "/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"
        ]
      }
    },
    "/v1/images/bulk": {
      "post": {
        "summary": "Start bulk image generation",
        "description": "Generate featured images for multiple articles at once. Returns a request ID to poll for status.\nRequires any plan (Solo or higher).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "article_ids"
                ],
                "properties": {
                  "article_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "minItems": 1,
                    "maxItems": 50,
                    "description": "Array of article IDs to generate images for"
                  },
                  "model": {
                    "type": "string",
                    "default": "gpt-image-2",
                    "description": "Image generation model to use"
                  },
                  "use_brand_colors": {
                    "type": "boolean",
                    "default": false,
                    "description": "Whether to incorporate brand colors into images"
                  },
                  "prompt_template": {
                    "type": "string",
                    "description": "Optional custom prompt template"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Bulk image generation started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "total_articles": {
                      "type": "number"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "queued"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Images"
        ]
      }
    },
    "/v1/images/bulk/{requestId}": {
      "get": {
        "summary": "Get bulk image generation status",
        "description": "Poll for the status of a bulk image generation request.",
        "parameters": [
          {
            "in": "path",
            "name": "requestId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The bulk request ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Bulk image status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "request_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "waiting",
                        "processing",
                        "completed",
                        "failed",
                        "canceled"
                      ]
                    },
                    "total_articles": {
                      "type": "number"
                    },
                    "completed_articles": {
                      "type": "number"
                    },
                    "failed_articles": {
                      "type": "number"
                    },
                    "model": {
                      "type": "string"
                    },
                    "articles": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "object",
                        "properties": {
                          "status": {
                            "type": "string"
                          },
                          "image_url": {
                            "type": "string",
                            "nullable": true
                          },
                          "error": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Images"
        ]
      },
      "delete": {
        "summary": "Cancel bulk image generation",
        "parameters": [
          {
            "in": "path",
            "name": "requestId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Canceled successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Images"
        ]
      }
    },
    "/v1/clusters/generate": {
      "post": {
        "summary": "Generate a content cluster",
        "description": "Create an interlinked content cluster with a pillar article and supporting articles.\nAll articles are automatically interlinked using Link Engine.\nRequires any plan (Solo or higher). If the site has no Link Engine URL pattern,\nCuppa auto-derives `https://{domain}/{slug}/` from the site domain. You may\noverride with optional `url_pattern` (must include `{slug}`).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "pillar_keyword",
                  "supporting_keywords"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "pillar_keyword": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "The main topic/keyword for the pillar article"
                  },
                  "pillar_title": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "Optional custom title for pillar article"
                  },
                  "pillar_secondary_keywords": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 5
                  },
                  "supporting_keywords": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 10,
                    "description": "Keywords for supporting articles that link to the pillar"
                  },
                  "url_pattern": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Optional article URL pattern (e.g. https://example.com/blog/{slug}/).\nWhen omitted, derived from site domain as https://{domain}/{slug}/.\n"
                  },
                  "options": {
                    "type": "object",
                    "properties": {
                      "article_type": {
                        "type": "string",
                        "enum": [
                          "general",
                          "listicle",
                          "review",
                          "howto"
                        ]
                      },
                      "word_count": {
                        "type": "number",
                        "minimum": 500,
                        "maximum": 5000
                      },
                      "language": {
                        "type": "string"
                      },
                      "model": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Cluster generation started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "cluster_id": {
                      "type": "string"
                    },
                    "total_articles": {
                      "type": "number"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "queued"
                      ]
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Clusters"
        ]
      }
    },
    "/v1/clusters": {
      "get": {
        "summary": "List keyword clusters",
        "description": "Returns keyword clusters for content planning. Requires any plan (Solo 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"
        ]
      }
    },
    "/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"
        ]
      }
    },
    "/v1/clusters/{id}/activate": {
      "post": {
        "summary": "Activate a cluster",
        "description": "Mark a cluster as \"In Plan\" for content planning. Requires any plan (Solo 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"
        ]
      }
    },
    "/v1/clusters/{id}/deactivate": {
      "post": {
        "summary": "Deactivate a cluster",
        "description": "Remove a cluster from \"In Plan\". Requires any plan (Solo 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"
        ]
      }
    },
    "/v1/planner": {
      "get": {
        "summary": "List content planner items",
        "description": "Returns scheduled content items. Requires any plan (Solo 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"
        ]
      },
      "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"
        ]
      }
    },
    "/v1/planner/{id}": {
      "get": {
        "summary": "Get a planner item",
        "description": "Get a single planner item by keyword_id. Requires any plan (Solo 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"
        ]
      },
      "put": {
        "summary": "Update a planner item",
        "description": "Update the scheduled date or status of a planner item. Requires any plan (Solo 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": {
        "summary": "Delete a planner item",
        "description": "Remove a scheduled item from the content planner. Cannot delete created/published items. Requires any plan (Solo 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"
        ]
      }
    },
    "/v1/planner/calendar": {
      "get": {
        "summary": "Get unified content calendar",
        "description": "Returns the unified content calendar showing all scheduled articles,\nlocal pages, and social posts grouped by date. Requires Solo plan\nor higher.\n",
        "parameters": [
          {
            "in": "query",
            "name": "site_id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Site/brand ID"
          },
          {
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string",
              "enum": [
                "scheduled",
                "created",
                "published"
              ]
            },
            "description": "Filter by status (default scheduled)"
          },
          {
            "in": "query",
            "name": "from_date",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Start date filter (YYYY-MM-DD)"
          },
          {
            "in": "query",
            "name": "to_date",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "End date filter (YYYY-MM-DD)"
          }
        ],
        "responses": {
          "200": {
            "description": "Unified content calendar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "object",
                      "description": "Items grouped by date (YYYY-MM-DD keys)",
                      "additionalProperties": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": [
                                "article",
                                "local",
                                "social_post"
                              ]
                            },
                            "id": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    "counts": {
                      "type": "object",
                      "properties": {
                        "article": {
                          "type": "integer"
                        },
                        "local": {
                          "type": "integer"
                        },
                        "social_post": {
                          "type": "integer"
                        }
                      }
                    },
                    "totalCount": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Planner"
        ]
      }
    },
    "/v1/planner/events": {
      "get": {
        "summary": "List planner events (holidays, custom dates, product launches)",
        "parameters": [
          {
            "in": "query",
            "name": "site_id",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by site ID"
          },
          {
            "in": "query",
            "name": "from_date",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Include events on or after this date"
          },
          {
            "in": "query",
            "name": "to_date",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Include events on or before this date"
          },
          {
            "in": "query",
            "name": "event_type",
            "schema": {
              "type": "string",
              "enum": [
                "holiday",
                "cultural",
                "industry",
                "custom",
                "product_launch",
                "seasonal"
              ]
            },
            "description": "Filter by event type"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of planner events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PlannerEvent"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Planner"
        ]
      },
      "post": {
        "summary": "Create a planner event",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title",
                  "event_date"
                ],
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "event_date": {
                    "type": "string",
                    "format": "date"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "description": {
                    "type": "string"
                  },
                  "event_type": {
                    "type": "string",
                    "enum": [
                      "holiday",
                      "cultural",
                      "industry",
                      "custom",
                      "product_launch",
                      "seasonal"
                    ]
                  },
                  "recurrence": {
                    "type": "string",
                    "enum": [
                      "none",
                      "annual",
                      "monthly",
                      "weekly"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Planner event created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlannerEvent"
                }
              }
            }
          }
        },
        "tags": [
          "Planner"
        ]
      }
    },
    "/v1/planner/events/{id}": {
      "get": {
        "summary": "Get a planner event by ID",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Planner event",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlannerEvent"
                }
              }
            }
          }
        },
        "tags": [
          "Planner"
        ]
      },
      "patch": {
        "summary": "Update a planner event",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "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"
                    ]
                  },
                  "metadata": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Planner event updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlannerEvent"
                }
              }
            }
          }
        },
        "tags": [
          "Planner"
        ]
      },
      "delete": {
        "summary": "Delete a planner event",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Planner event deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "success": true
                }
              }
            }
          }
        },
        "tags": [
          "Planner"
        ]
      }
    },
    "/v1/research/keywords": {
      "post": {
        "summary": "Research keyword opportunities",
        "description": "Get keyword ideas from seed keywords using DataForSEO. Returns search volume, difficulty, and intent data.\nRequires any plan (Solo or higher).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "seed_keywords"
                ],
                "properties": {
                  "seed_keywords": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 10,
                    "description": "Seed keywords to research"
                  },
                  "location": {
                    "type": "string",
                    "default": "United States"
                  },
                  "language": {
                    "type": "string",
                    "default": "en"
                  },
                  "include_questions": {
                    "type": "boolean",
                    "default": true
                  },
                  "limit": {
                    "type": "number",
                    "minimum": 1,
                    "maximum": 500,
                    "default": 50
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Keyword research results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "keywords": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "keyword": {
                            "type": "string"
                          },
                          "search_volume": {
                            "type": "number"
                          },
                          "keyword_difficulty": {
                            "type": "number"
                          },
                          "cpc": {
                            "type": "number"
                          },
                          "competition": {
                            "type": "string"
                          },
                          "search_intent": {
                            "type": "string"
                          },
                          "is_question": {
                            "type": "boolean"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "number"
                    },
                    "seed_keywords": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "location": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Research"
        ]
      }
    },
    "/v1/research/serp": {
      "post": {
        "summary": "Analyze SERP for a keyword",
        "description": "Get detailed SERP analysis including organic results, SERP features, People Also Ask, and search intent.\nRequires any plan (Solo or higher).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "keyword"
                ],
                "properties": {
                  "keyword": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "location": {
                    "type": "string",
                    "default": "United States"
                  },
                  "language": {
                    "type": "string",
                    "default": "en"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SERP analysis results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "keyword": {
                      "type": "string"
                    },
                    "location": {
                      "type": "string"
                    },
                    "search_intent": {
                      "type": "string",
                      "enum": [
                        "informational",
                        "commercial",
                        "transactional",
                        "local"
                      ]
                    },
                    "difficulty": {
                      "type": "string",
                      "enum": [
                        "Low",
                        "Medium",
                        "High"
                      ]
                    },
                    "serp_features": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "organic_results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "position": {
                            "type": "number"
                          },
                          "url": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "domain": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "people_also_ask": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "unique_domains": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Research"
        ]
      }
    },
    "/v1/research/competitors": {
      "post": {
        "summary": "Analyze competitor keywords",
        "description": "Get keywords that a competitor domain ranks for. Useful for competitive analysis and content gap identification.\nRequires any plan (Solo or higher).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "description": "Competitor domain to analyze (e.g., \"competitor.com\")"
                  },
                  "location": {
                    "type": "string",
                    "default": "United States"
                  },
                  "limit": {
                    "type": "number",
                    "minimum": 1,
                    "maximum": 200,
                    "default": 50
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Competitor keyword analysis",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "domain": {
                      "type": "string"
                    },
                    "keywords": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "keyword": {
                            "type": "string"
                          },
                          "search_volume": {
                            "type": "number"
                          },
                          "keyword_difficulty": {
                            "type": "number"
                          },
                          "cpc": {
                            "type": "number"
                          },
                          "competition": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "number"
                    },
                    "total_volume": {
                      "type": "number"
                    },
                    "competition_breakdown": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "number"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Research"
        ]
      }
    },
    "/v1/research/trends": {
      "post": {
        "summary": "Google Trends data",
        "description": "Get Google Trends data for keywords: popularity over time, rising topics, breakout queries, and trend direction.\nUseful for validating content ideas, finding trending topics, and discovering what people are searching for.\nSupports web, news, YouTube, and image search types.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "keywords"
                ],
                "properties": {
                  "keywords": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 5,
                    "description": "Keywords to check trends for (max 5)"
                  },
                  "location": {
                    "type": "string",
                    "description": "Location name (e.g. \"United States\")"
                  },
                  "time_range": {
                    "type": "string",
                    "enum": [
                      "past_hour",
                      "past_4_hours",
                      "past_day",
                      "past_7_days",
                      "past_30_days",
                      "past_90_days",
                      "past_12_months",
                      "past_5_years"
                    ],
                    "default": "past_12_months",
                    "description": "Time range for trend data"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "web",
                      "news",
                      "youtube",
                      "images"
                    ],
                    "default": "web",
                    "description": "Search type"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Trend data with direction, related topics, and rising queries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "keywords": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "location": {
                          "type": "string"
                        },
                        "timeRange": {
                          "type": "string"
                        },
                        "searchType": {
                          "type": "string"
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Research"
        ]
      }
    },
    "/v1/research/web-search": {
      "post": {
        "summary": "Web search via Perplexity",
        "description": "Search the web for real-time information using Perplexity Sonar Pro.\nReturns a structured analysis with citations. Use for trending social media topics,\nindustry news, competitor activity, viral content formats, or any question requiring current information.\nRequires a Perplexity API key in team settings.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500,
                    "description": "Search query for web research"
                  },
                  "focus": {
                    "type": "string",
                    "enum": [
                      "general",
                      "social_trends",
                      "industry_news",
                      "competitor_analysis"
                    ],
                    "default": "general",
                    "description": "Focus area to refine the search context"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Structured research result with citations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "query": {
                          "type": "string"
                        },
                        "focus": {
                          "type": "string"
                        },
                        "result": {
                          "type": "string",
                          "description": "Structured analysis text"
                        },
                        "citations": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "usage": {
                          "type": "object",
                          "properties": {
                            "promptTokens": {
                              "type": "integer"
                            },
                            "completionTokens": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Research"
        ]
      }
    },
    "/v1/brand/listen": {
      "post": {
        "summary": "Listen for brand mentions",
        "description": "Scan social platforms for brand or competitor mentions.\nRequires `brand` plus `category`, `handle`, or `domain` so name collisions\nare dropped. Complements web mention tools. Does not publish.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand"
                ],
                "properties": {
                  "brand": {
                    "type": "string"
                  },
                  "category": {
                    "type": "string"
                  },
                  "handle": {
                    "type": "string"
                  },
                  "domain": {
                    "type": "string"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "platforms": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "x",
                        "reddit",
                        "youtube",
                        "instagram",
                        "tiktok",
                        "linkedin"
                      ]
                    }
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 25
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mention list after collision filtering"
          }
        },
        "tags": [
          "Brand Intel"
        ]
      }
    },
    "/v1/brand/reviews": {
      "post": {
        "summary": "Scan public reviews",
        "description": "Mine Amazon or Trustpilot reviews. Trustpilot may return pending if the pull is queued.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "source",
                  "target"
                ],
                "properties": {
                  "source": {
                    "type": "string",
                    "enum": [
                      "amazon",
                      "trustpilot",
                      "google"
                    ]
                  },
                  "target": {
                    "type": "string",
                    "description": "Amazon ASIN, Trustpilot domain, or Google place / business name"
                  },
                  "location": {
                    "type": "string",
                    "description": "Location for google source"
                  },
                  "task_id": {
                    "type": "string",
                    "description": "Retry a queued review pull"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "limit": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reviews or a pending task"
          }
        },
        "tags": [
          "Brand Intel"
        ]
      }
    },
    "/v1/brand/competitor-ads": {
      "post": {
        "summary": "Competitor ads",
        "description": "Google Ads Transparency and Meta Ad Library teardown. Pass domain, page_id, or advertiser. Not a bare keyword.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string"
                  },
                  "page_id": {
                    "type": "string"
                  },
                  "advertiser": {
                    "type": "string"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "platforms": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "google",
                        "meta"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Filtered competitor ads"
          }
        },
        "tags": [
          "Brand Intel"
        ]
      }
    },
    "/v1/brand/people": {
      "post": {
        "summary": "Find a person",
        "description": "Work email from name + domain or LinkedIn. Verifies before `send_ok`. Do not send mail from this endpoint. Studio+ only.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "full_name": {
                    "type": "string"
                  },
                  "first_name": {
                    "type": "string"
                  },
                  "last_name": {
                    "type": "string"
                  },
                  "domain": {
                    "type": "string"
                  },
                  "linkedin_url": {
                    "type": "string"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "verify": {
                    "type": "boolean",
                    "default": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Found email plus verification"
          }
        },
        "tags": [
          "Brand Intel"
        ]
      }
    },
    "/v1/brand/creators": {
      "post": {
        "summary": "Find creators",
        "description": "Shortlist creators. Keep limit small. Screen before outreach. Studio+ only.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "platform"
                ],
                "properties": {
                  "platform": {
                    "type": "string",
                    "enum": [
                      "instagram",
                      "youtube",
                      "tiktok",
                      "twitter"
                    ]
                  },
                  "query": {
                    "type": "string"
                  },
                  "bio_keywords": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "country": {
                    "type": "string"
                  },
                  "min_followers": {
                    "type": "integer"
                  },
                  "limit": {
                    "type": "integer",
                    "maximum": 10
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Creator shortlist"
          }
        },
        "tags": [
          "Brand Intel"
        ]
      }
    },
    "/v1/brand/company": {
      "post": {
        "summary": "Enrich a company",
        "description": "Firmographics from domain, name, LinkedIn, or work email. Studio+ only.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "website": {
                    "type": "string"
                  },
                  "linkedin_url": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Company firmographics"
          }
        },
        "tags": [
          "Brand Intel"
        ]
      }
    },
    "/v1/brand/ugc": {
      "post": {
        "summary": "Generate a UGC talking-head take",
        "description": "Quotes a Seedance talking-head clip unless `confirm_paid` is true.\nRequires a locked character still and a 2-15s voice reference.\nDoes not publish. Studio+.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "script",
                  "character_image_url",
                  "voice_url"
                ],
                "properties": {
                  "script": {
                    "type": "string"
                  },
                  "character_image_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "voice_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "product": {
                    "type": "string"
                  },
                  "top": {
                    "type": "string"
                  },
                  "prop": {
                    "type": "string"
                  },
                  "confirm_paid": {
                    "type": "boolean",
                    "default": false
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote or queued video id"
          }
        },
        "tags": [
          "Brand Intel"
        ]
      }
    },
    "/v1/integrations/slack/command": {
      "post": {
        "summary": "Run a Cuppa command via Slack",
        "description": "Run a Cuppa command (the same commands available via the `/cuppa` Slack\nslash command and `@Cuppa` mentions) and optionally post the result into\na Slack channel. Runs synchronously and returns the resulting Slack\nBlock Kit blocks plus a plain-text summary.\n\nFor teams with many brands, always include `site=domain.com` in the\ncommand to target a specific brand.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "command"
                ],
                "properties": {
                  "command": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1500,
                    "description": "The command without the `/cuppa` prefix. Examples:\n`generate keyword=\"best coffee makers\" site=example.com`,\n`bulk keywords=\"a, b, c\" site=example.com`, `status`, `summary weekly`.\n"
                  },
                  "channel": {
                    "type": "string",
                    "maxLength": 64,
                    "description": "Optional Slack channel ID to post the result into."
                  },
                  "thread_ts": {
                    "type": "string",
                    "description": "Optional Slack thread timestamp to reply into."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Command executed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "action": {
                          "type": "string",
                          "description": "The parsed command action (e.g. generate, bulk, status)."
                        },
                        "posted": {
                          "type": "boolean",
                          "description": "Whether the result was posted to a Slack channel."
                        },
                        "text": {
                          "type": "string",
                          "description": "Plain-text summary of the result."
                        },
                        "blocks": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          },
                          "description": "Slack Block Kit blocks for the result."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or Slack not connected"
          }
        },
        "tags": [
          "Integrations"
        ]
      }
    },
    "/v1/integrations/slack/propose": {
      "post": {
        "summary": "Propose a Cuppa command in Slack (Approve/Reject)",
        "description": "Post a Cuppa command into a Slack channel as an Approve/Reject card. A\nhuman approves it in Slack, then Cuppa runs the command. Use this for\nhuman-gated automation loops (e.g. an agent drafts commands for review).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "command",
                  "channel"
                ],
                "properties": {
                  "command": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1500,
                    "description": "The command without the `/cuppa` prefix."
                  },
                  "channel": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 64,
                    "description": "Slack channel ID to post the Approve/Reject card into."
                  },
                  "thread_ts": {
                    "type": "string",
                    "description": "Optional Slack thread timestamp to post the card into."
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Optional note shown above the Approve/Reject buttons."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Proposal card posted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "channel": {
                          "type": "string"
                        },
                        "ts": {
                          "type": "string",
                          "description": "Timestamp of the posted Slack message."
                        },
                        "command": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or Slack not connected"
          },
          "502": {
            "description": "Failed to post to Slack"
          }
        },
        "tags": [
          "Integrations"
        ]
      }
    },
    "/v1/research/cluster": {
      "post": {
        "summary": "Cluster keywords by intent and topic",
        "description": "Group keywords by search intent (informational, commercial, transactional, navigational) and topic clusters.\nUseful for content planning and site architecture.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "keywords"
                ],
                "properties": {
                  "keywords": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 500
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "intent",
                      "topic",
                      "both"
                    ],
                    "default": "both"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Keyword clustering results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "intent_clusters": {
                      "type": "object",
                      "properties": {
                        "informational": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "commercial": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "transactional": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "navigational": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "topic_clusters": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "keywords": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "count": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "total_keywords": {
                      "type": "number"
                    },
                    "method": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Research"
        ]
      }
    },
    "/v1/sites/{id}/gsc/queries": {
      "get": {
        "summary": "Get GSC search queries for a site",
        "description": "Returns Google Search Console query data including clicks, impressions, position, and opportunity scores.\nRequires any plan (Solo or higher) and GSC to be connected.\n",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The site ID"
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "maximum": 500,
              "default": 100
            }
          },
          {
            "in": "query",
            "name": "min_impressions",
            "schema": {
              "type": "integer"
            },
            "description": "Filter queries with at least this many impressions"
          },
          {
            "in": "query",
            "name": "max_position",
            "schema": {
              "type": "integer"
            },
            "description": "Filter queries ranking at or above this position"
          },
          {
            "in": "query",
            "name": "sort_by",
            "schema": {
              "type": "string",
              "enum": [
                "position",
                "impressions",
                "clicks",
                "opportunity_score"
              ],
              "default": "impressions"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "GSC query data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "queries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "query": {
                            "type": "string"
                          },
                          "page_url": {
                            "type": "string",
                            "nullable": true
                          },
                          "clicks": {
                            "type": "number"
                          },
                          "impressions": {
                            "type": "number"
                          },
                          "ctr": {
                            "type": "number"
                          },
                          "position": {
                            "type": "number"
                          },
                          "opportunity_score": {
                            "type": "number",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "number"
                    },
                    "gsc_connected": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Sites"
        ]
      }
    },
    "/v1/contents/{id}/publish": {
      "post": {
        "summary": "Publish article to CMS platform",
        "description": "Push an article to an external CMS or static-site integration\n(Ghost, Webflow, Contentful, Sanity, Airtable, Shopify, Vercel, Astro).\nThe integration must be configured in team settings first.\nRequires any plan (Solo 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",
                      "vercel",
                      "astro"
                    ]
                  },
                  "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"
        ]
      }
    },
    "/v1/chat/completions": {
      "post": {
        "summary": "Chat with Cuppa AI agent",
        "description": "Send messages to Cuppa AI agent with access to research tools.\nThe agent can research keywords, analyze competitors, check SERP data, and provide content strategy insights.\nRequires any plan (Solo or higher).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "role",
                        "content"
                      ],
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "user",
                            "assistant",
                            "system"
                          ]
                        },
                        "content": {
                          "type": "string"
                        }
                      }
                    },
                    "minItems": 1
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Site ID for brand context. If not provided, uses first active site."
                  },
                  "model": {
                    "type": "string",
                    "default": "gpt-6-luna",
                    "description": "The model to use for chat. Examples - gpt-6.2-sol, gpt-6-luna, gpt-6.2-astra, claude-opus-5-5, grok-4.7. Use `/v1/meta/models` for the full list."
                  },
                  "audio": {
                    "type": "object",
                    "description": "Optional audio input. Transcribed via STT, then appended as a user message.",
                    "properties": {
                      "url": {
                        "type": "string",
                        "format": "uri"
                      },
                      "base64": {
                        "type": "string"
                      },
                      "provider": {
                        "type": "string",
                        "enum": [
                          "gpt-live-1",
                          "grok-voice-latest"
                        ]
                      }
                    }
                  },
                  "tools": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "research_keywords",
                        "analyze_serp",
                        "get_striking_distance",
                        "cluster_keywords",
                        "get_articles",
                        "get_brand_context",
                        "get_site_pages",
                        "get_gsc_performance",
                        "get_brand_performance",
                        "get_performance_pages",
                        "analyze_competitor_keywords"
                      ]
                    },
                    "description": "Which tools to enable. Defaults to all tools."
                  },
                  "max_tokens": {
                    "type": "integer",
                    "minimum": 100,
                    "maximum": 16000,
                    "default": 4000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Chat completion response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "object",
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "assistant"
                          ]
                        },
                        "content": {
                          "type": "string"
                        }
                      }
                    },
                    "tool_calls": {
                      "type": "array",
                      "description": "Tools that were called during the conversation",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tool": {
                            "type": "string"
                          },
                          "input": {
                            "type": "object"
                          },
                          "output": {
                            "type": "object"
                          },
                          "success": {
                            "type": "boolean"
                          }
                        }
                      }
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "prompt_tokens": {
                          "type": "integer"
                        },
                        "completion_tokens": {
                          "type": "integer"
                        },
                        "total_tokens": {
                          "type": "integer"
                        }
                      }
                    },
                    "model": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Chat"
        ]
      }
    },
    "/v1/voice/stt": {
      "post": {
        "summary": "Transcribe audio to text",
        "description": "Speech-to-text via OpenAI Whisper (default) or xAI.\nAccepts multipart `audio` file or JSON `{ url }` / `{ audio_base64 }`.\n",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "audio": {
                    "type": "string",
                    "format": "binary"
                  },
                  "provider": {
                    "type": "string",
                    "enum": [
                      "gpt-live-1",
                      "grok-voice-latest"
                    ]
                  }
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "audio_base64": {
                    "type": "string"
                  },
                  "provider": {
                    "type": "string",
                    "enum": [
                      "gpt-live-1",
                      "grok-voice-latest"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transcription",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "text": {
                      "type": "string"
                    },
                    "provider": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Voice"
        ]
      }
    },
    "/v1/voice/tts": {
      "post": {
        "summary": "Text to speech",
        "description": "Synthesize speech. Returns base64 MP3.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 4000
                  },
                  "provider": {
                    "type": "string",
                    "enum": [
                      "gpt-live-1",
                      "grok-voice-latest"
                    ]
                  },
                  "voice": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audio payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "audio_base64": {
                      "type": "string"
                    },
                    "content_type": {
                      "type": "string"
                    },
                    "provider": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Voice"
        ]
      }
    },
    "/v1/voice/session": {
      "post": {
        "summary": "Create live voice session",
        "description": "Returns OpenAI Live WebRTC SDP answer (when `sdp` provided) or xAI ephemeral client secret.\nAttach your own mic client; Cuppa web is the first-class duplex client.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string",
                    "enum": [
                      "gpt-live-1",
                      "grok-voice-latest"
                    ]
                  },
                  "sdp": {
                    "type": "string",
                    "description": "WebRTC SDP offer (required for gpt-live-1)"
                  },
                  "instructions": {
                    "type": "string"
                  },
                  "chat_model": {
                    "type": "string"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session credentials",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "type": "string"
                    },
                    "session_id": {
                      "type": "string",
                      "nullable": true
                    },
                    "sdp": {
                      "type": "string",
                      "nullable": true
                    },
                    "client_secret": {
                      "type": "string"
                    },
                    "ws_url": {
                      "type": "string"
                    },
                    "model": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Voice"
        ]
      }
    },
    "/v1/social/publish": {
      "post": {
        "summary": "Publish social post immediately",
        "description": "Publish a social media post immediately to a connected platform via Late.dev.\nThe social account must be connected in Brand Settings first.\nRequires any plan (Solo or higher).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "platform",
                  "content"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "platform": {
                    "type": "string",
                    "enum": [
                      "twitter",
                      "linkedin",
                      "instagram",
                      "facebook",
                      "threads",
                      "tiktok",
                      "pinterest",
                      "youtube",
                      "bluesky",
                      "telegram"
                    ]
                  },
                  "content": {
                    "type": "string",
                    "maxLength": 5000
                  },
                  "hashtags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "image_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "video_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "URL of a video to attach (preferred over image_url for video platforms like TikTok, YouTube)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Post published",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "platform": {
                      "type": "string"
                    },
                    "post_id": {
                      "type": "string",
                      "nullable": true
                    },
                    "late_post_id": {
                      "type": "string",
                      "nullable": true
                    },
                    "error": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/social/schedule": {
      "post": {
        "summary": "Schedule social post for future publishing",
        "description": "Schedule a social media post for future publishing.\nThe post is sent to Late.dev with the scheduled time.\nRequires any plan (Solo or higher).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "platform",
                  "content",
                  "scheduled_at"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "platform": {
                    "type": "string",
                    "enum": [
                      "twitter",
                      "linkedin",
                      "instagram",
                      "facebook",
                      "threads",
                      "tiktok",
                      "pinterest",
                      "youtube",
                      "bluesky",
                      "telegram"
                    ]
                  },
                  "content": {
                    "type": "string",
                    "maxLength": 5000
                  },
                  "scheduled_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "ISO datetime when the post should be published"
                  },
                  "hashtags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "image_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "video_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "URL of a video to attach (preferred over image_url for video platforms like TikTok, YouTube)"
                  },
                  "article_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional article ID to link this post to"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Post scheduled",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "platform": {
                      "type": "string"
                    },
                    "post_id": {
                      "type": "string",
                      "nullable": true
                    },
                    "late_post_id": {
                      "type": "string",
                      "nullable": true
                    },
                    "scheduled_at": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "scheduled",
                        "draft"
                      ]
                    },
                    "warning": {
                      "type": "string",
                      "nullable": true,
                      "description": "Warning message if post was saved as draft"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/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 any plan (Solo 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"
        ]
      }
    },
    "/v1/social/multi": {
      "post": {
        "summary": "Generate social posts for multiple platforms",
        "description": "Generate optimized social media posts for up to 5 platforms at once.\nEach platform gets tailored content based on its character limits\nand best practices. Provide article_title + article_summary,\nor topic for standalone posts. Requires any plan (Solo or higher).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "platforms"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Site/brand ID"
                  },
                  "topic": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Standalone topic (alternative to article fields)"
                  },
                  "article_title": {
                    "type": "string",
                    "description": "Title of the article"
                  },
                  "article_summary": {
                    "type": "string",
                    "description": "Brief summary of the article"
                  },
                  "article_url": {
                    "type": "string",
                    "description": "Public URL of the article"
                  },
                  "platforms": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "twitter",
                        "instagram",
                        "facebook",
                        "linkedin",
                        "tiktok",
                        "youtube",
                        "pinterest",
                        "bluesky",
                        "threads",
                        "telegram"
                      ]
                    },
                    "minItems": 1,
                    "maxItems": 5,
                    "description": "Target platforms (1-5)"
                  },
                  "tone": {
                    "type": "string",
                    "enum": [
                      "casual",
                      "professional",
                      "witty",
                      "inspiring",
                      "educational",
                      "engaging"
                    ],
                    "default": "engaging"
                  },
                  "include_hashtags": {
                    "type": "boolean",
                    "default": true
                  },
                  "generate_images": {
                    "type": "boolean",
                    "default": false,
                    "description": "Generate images for each platform (requires Replicate API key)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Posts generated for each platform",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "$ref": "#/components/schemas/SocialPost"
                  },
                  "description": "Map of platform name to generated post"
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/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"
        ]
      }
    },
    "/v1/social/posts": {
      "get": {
        "summary": "List social posts",
        "description": "List social media posts with optional filters.",
        "parameters": [
          {
            "in": "query",
            "name": "page",
            "schema": {
              "type": "integer"
            },
            "description": "Page number for pagination"
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            },
            "description": "Maximum number of posts to return"
          },
          {
            "in": "query",
            "name": "site_id",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by site ID"
          },
          {
            "in": "query",
            "name": "platform",
            "schema": {
              "type": "string"
            },
            "description": "Filter by platform"
          },
          {
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "scheduled",
                "published",
                "failed"
              ]
            },
            "description": "Filter by status"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of social posts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "posts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SocialPostRecord"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "page": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/social/posts/{id}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Social post ID"
        }
      ],
      "get": {
        "summary": "Get social post",
        "description": "Get a single social post by ID.",
        "responses": {
          "200": {
            "description": "The social post",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SocialPostRecord"
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      },
      "patch": {
        "summary": "Update social post",
        "description": "Update a draft or scheduled social post. Cannot edit published posts.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content": {
                    "type": "string"
                  },
                  "hashtags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "scheduled_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "image_url": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Post updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SocialPostRecord"
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      },
      "delete": {
        "summary": "Delete social post",
        "description": "Delete a draft or scheduled social post. Cannot delete published posts.",
        "responses": {
          "200": {
            "description": "Post deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/social/posts/{id}/schedule": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Social post ID (must be in draft status)"
        }
      ],
      "post": {
        "summary": "Schedule a draft social post",
        "description": "Takes an existing draft social post and schedules it via Late.dev.\nUses the post's scheduled_at timestamp, or defaults to tomorrow 9am UTC.\nThe post must be in \"draft\" status and have a connected platform account.\n",
        "responses": {
          "200": {
            "description": "Post scheduled",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "scheduled"
                      ]
                    },
                    "late_post_id": {
                      "type": "string"
                    },
                    "scheduled_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Post cannot be scheduled (not draft, no account connected, etc.)"
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/social/posts/{id}/publish": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Social post ID (must be in draft status)"
        }
      ],
      "post": {
        "summary": "Publish a draft social post immediately",
        "description": "Takes an existing draft social post and publishes it immediately via Late.dev.\nThe post must be in \"draft\" status and have a connected platform account.\n",
        "responses": {
          "200": {
            "description": "Post published",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "published"
                      ]
                    },
                    "late_post_id": {
                      "type": "string"
                    },
                    "published_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Post cannot be published (not draft, no account connected, etc.)"
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/social/posts/bulk-schedule": {
      "post": {
        "summary": "Bulk schedule or publish draft social posts",
        "description": "Schedule or publish multiple draft social posts at once. Processes posts\nsequentially to respect Late.dev rate limits. Returns partial success:\nindividual post failures don't block others.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "post_ids"
                ],
                "properties": {
                  "post_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "minItems": 1,
                    "maxItems": 50,
                    "description": "Array of draft social post IDs"
                  },
                  "action": {
                    "type": "string",
                    "enum": [
                      "schedule",
                      "publish"
                    ],
                    "default": "schedule",
                    "description": "Action to perform on each post"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bulk operation results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "scheduled",
                              "published",
                              "failed"
                            ]
                          },
                          "late_post_id": {
                            "type": "string"
                          },
                          "scheduled_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "published_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "error": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/social/analytics": {
      "get": {
        "summary": "Get social media analytics",
        "description": "Returns social media analytics for a site including impressions,\nengagements, clicks, shares, per-platform breakdowns, and top\nperforming posts. Requires Solo plan or higher.\n",
        "parameters": [
          {
            "in": "query",
            "name": "site_id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Site/brand ID"
          },
          {
            "in": "query",
            "name": "platform",
            "schema": {
              "type": "string"
            },
            "description": "Filter by platform (e.g. twitter, linkedin)"
          },
          {
            "in": "query",
            "name": "from_date",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Start date filter (ISO 8601)"
          },
          {
            "in": "query",
            "name": "to_date",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "End date filter (ISO 8601)"
          },
          {
            "in": "query",
            "name": "top_n",
            "schema": {
              "type": "integer",
              "default": 5,
              "maximum": 20
            },
            "description": "Number of top posts to include"
          }
        ],
        "responses": {
          "200": {
            "description": "Social analytics summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "totalPosts": {
                      "type": "integer"
                    },
                    "totalImpressions": {
                      "type": "integer"
                    },
                    "totalEngagements": {
                      "type": "integer"
                    },
                    "totalClicks": {
                      "type": "integer"
                    },
                    "totalShares": {
                      "type": "integer"
                    },
                    "averageEngagementRate": {
                      "type": "number"
                    },
                    "byPlatform": {
                      "type": "object",
                      "description": "Per-platform breakdown",
                      "additionalProperties": {
                        "type": "object",
                        "properties": {
                          "posts": {
                            "type": "integer"
                          },
                          "impressions": {
                            "type": "integer"
                          },
                          "engagements": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "topPosts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "platform": {
                            "type": "string"
                          },
                          "content": {
                            "type": "string"
                          },
                          "analytics": {
                            "type": "object",
                            "properties": {
                              "impressions": {
                                "type": "integer"
                              },
                              "engagements": {
                                "type": "integer"
                              },
                              "clicks": {
                                "type": "integer"
                              },
                              "engagement_rate": {
                                "type": "number"
                              }
                            }
                          }
                        }
                      }
                    },
                    "period": {
                      "type": "object",
                      "properties": {
                        "from": {
                          "type": "string",
                          "nullable": true
                        },
                        "to": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/social/inbox": {
      "get": {
        "summary": "List social inbox items",
        "description": "Returns social inbox items (comments, DMs, mentions) synced from\nconnected social accounts. Requires any plan (Solo or higher).\n",
        "parameters": [
          {
            "in": "query",
            "name": "site_id",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by site/brand"
          },
          {
            "in": "query",
            "name": "platform",
            "schema": {
              "type": "string"
            },
            "description": "Filter by platform (e.g. instagram, youtube)"
          },
          {
            "in": "query",
            "name": "item_type",
            "schema": {
              "type": "string",
              "enum": [
                "comment",
                "message",
                "mention",
                "review"
              ]
            },
            "description": "Filter by item type"
          },
          {
            "in": "query",
            "name": "is_read",
            "schema": {
              "type": "boolean"
            },
            "description": "Filter by read state"
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 100
            }
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Inbox items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/social/inbox/{id}/reply": {
      "post": {
        "summary": "Reply to an inbox item",
        "description": "Reply to a social comment or DM. X (Twitter) replies require X sync to\nbe enabled with a spend cap on the brand. Requires any plan (Solo or higher).\n",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Inbox item ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "message"
                ],
                "properties": {
                  "message": {
                    "type": "string",
                    "maxLength": 5000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reply sent",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/social/ads": {
      "get": {
        "summary": "List ads from connected platforms",
        "description": "Returns ads from all connected ad platforms (Meta, Google, TikTok,\nLinkedIn, Pinterest, X), including Cuppa-boosted posts and\nplatform-discovered ads, with live performance metrics pulled from\nZernio (`source=all`). Requires any plan (Solo or higher).\n\n**Platform filter values** (Zernio list API): `facebook`, `instagram`,\n`google`, `tiktok`, `linkedin`, `pinterest`, `twitter`.\n",
        "parameters": [
          {
            "in": "query",
            "name": "site_id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "query",
            "name": "ad_account_id",
            "schema": {
              "type": "string"
            },
            "description": "Filter to one connected billable ad account"
          },
          {
            "in": "query",
            "name": "campaign_id",
            "schema": {
              "type": "string"
            },
            "description": "Filter ads to one platform campaign ID"
          },
          {
            "in": "query",
            "name": "platform",
            "schema": {
              "type": "string",
              "enum": [
                "facebook",
                "instagram",
                "tiktok",
                "linkedin",
                "pinterest",
                "google",
                "twitter"
              ]
            },
            "description": "Filter by ad platform (Zernio list slug)"
          },
          {
            "in": "query",
            "name": "from_date",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Metrics window start (YYYY-MM-DD, default last 30 days)"
          },
          {
            "in": "query",
            "name": "to_date",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Metrics window end (YYYY-MM-DD, default today)"
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "default": 500,
              "maximum": 500
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ads list with aggregate totals",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ads": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SocialAd"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "totals": {
                      "$ref": "#/components/schemas/SocialAdTotals"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/social/ads/campaigns": {
      "get": {
        "summary": "List ad campaigns from connected platforms",
        "description": "Returns live campaigns aggregated from all connected ad platforms via\nZernio (`source=all`). Requires any plan (Solo or higher).\n\n**Platform filter values**: `facebook`, `instagram`, `google`,\n`tiktok`, `linkedin`, `pinterest`, `twitter`.\n",
        "parameters": [
          {
            "in": "query",
            "name": "site_id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "query",
            "name": "ad_account_id",
            "schema": {
              "type": "string"
            },
            "description": "Filter to one connected billable ad account"
          },
          {
            "in": "query",
            "name": "platform",
            "schema": {
              "type": "string",
              "enum": [
                "facebook",
                "instagram",
                "tiktok",
                "linkedin",
                "pinterest",
                "google",
                "twitter"
              ]
            },
            "description": "Filter by ad platform (Zernio list slug)"
          },
          {
            "in": "query",
            "name": "from_date",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "in": "query",
            "name": "to_date",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "in": "query",
            "name": "page",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Campaign list with aggregate totals",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "campaigns": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SocialAdCampaign"
                      }
                    },
                    "totals": {
                      "$ref": "#/components/schemas/SocialAdTotals"
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "pages": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/social/ads/accounts": {
      "get": {
        "summary": "List connected ad accounts",
        "description": "Returns connected ad accounts (Meta, Google, TikTok, etc.). Pass\nrefresh=true with a site_id to pull the latest from the provider first.\nRequires any plan (Solo or higher).\n",
        "parameters": [
          {
            "in": "query",
            "name": "site_id",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "query",
            "name": "refresh",
            "schema": {
              "type": "boolean"
            },
            "description": "Refresh from the ads provider before returning"
          }
        ],
        "responses": {
          "200": {
            "description": "Ad accounts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accounts": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/social/ads/boost": {
      "post": {
        "summary": "Boost an existing published post into a paid ad",
        "description": "Creates a paid ad from an existing published post, billed against the\ncustomer's connected ad account. Boost either a post published through\nCuppa (`post_id`) or any existing native platform post\n(`platform_post_id` + `site_id`). Requires any plan (Solo or higher).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ad_account_id",
                  "platform",
                  "name",
                  "goal",
                  "budget_amount",
                  "budget_type"
                ],
                "properties": {
                  "post_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Cuppa social post ID (must be published). Provide this or platform_post_id."
                  },
                  "platform_post_id": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "Native platform post ID to boost a post not published via Cuppa. Requires site_id."
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Site ID (required when using platform_post_id)"
                  },
                  "ad_account_id": {
                    "type": "string",
                    "description": "Platform ad account ID to bill against"
                  },
                  "platform": {
                    "type": "string",
                    "description": "Social platform the post was published on"
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "goal": {
                    "type": "string",
                    "enum": [
                      "engagement",
                      "reach",
                      "traffic",
                      "awareness",
                      "leads",
                      "sales",
                      "video_views"
                    ]
                  },
                  "budget_amount": {
                    "type": "number"
                  },
                  "budget_type": {
                    "type": "string",
                    "enum": [
                      "daily",
                      "lifetime"
                    ]
                  },
                  "schedule_start_date": {
                    "type": "string",
                    "description": "Run window start date (YYYY-MM-DD)"
                  },
                  "schedule_end_date": {
                    "type": "string",
                    "description": "Run window end date (YYYY-MM-DD)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ad created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "ad_id": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/social/ads/creatives": {
      "get": {
        "summary": "List generated ad creatives",
        "description": "Lists AI-generated paid ad creatives (copy + on-brand image) for a site.\nRequires any plan (Solo or higher).\n",
        "parameters": [
          {
            "in": "query",
            "name": "site_id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "saved",
                "discarded"
              ]
            }
          },
          {
            "in": "query",
            "name": "batch_id",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter to a single batch generation job"
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "maximum": 200,
              "default": 60
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of ad creatives",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "creatives": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AdCreative"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      },
      "post": {
        "summary": "Generate ad creative(s)",
        "description": "Generate paid ad copy and an on-brand creative image. Behavior depends\non the body:\n  - `count` > 1 runs an async batch (returns `request_id`; poll the\n    status endpoint, then list creatives by `batch_id`).\n  - `with_landing_page` = true (with `count` = 1) also creates a matching\n    landing page draft and links it to the creative.\n  - otherwise a single creative is returned inline.\nImage generation uses the team's Replicate key. Requires any plan (Solo or higher).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "platform",
                  "format",
                  "product_name"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "platform": {
                    "type": "string",
                    "enum": [
                      "meta",
                      "google",
                      "linkedin",
                      "tiktok",
                      "pinterest",
                      "twitter"
                    ]
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "feed_square",
                      "feed_portrait",
                      "story_reel",
                      "landscape",
                      "search_rsa"
                    ]
                  },
                  "product_name": {
                    "type": "string",
                    "maxLength": 300,
                    "description": "Product, brand, or offer being advertised"
                  },
                  "offer": {
                    "type": "string",
                    "maxLength": 1000
                  },
                  "angle": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "audience": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "target_keyword": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "landing_url": {
                    "type": "string",
                    "maxLength": 2048
                  },
                  "model": {
                    "type": "string",
                    "description": "AI model for copy generation"
                  },
                  "image_model": {
                    "type": "string",
                    "description": "Replicate image model"
                  },
                  "generate_image": {
                    "type": "boolean",
                    "default": true
                  },
                  "apply_brand_dna": {
                    "type": "boolean",
                    "default": true,
                    "description": "Write in brand voice and inject brand colors."
                  },
                  "custom_instructions": {
                    "type": "string",
                    "maxLength": 4000,
                    "description": "Extra creative direction for copy + image."
                  },
                  "custom_image_prompt": {
                    "type": "string",
                    "maxLength": 6000,
                    "description": "Full custom image prompt (single ad only; overrides the AI-written prompt)."
                  },
                  "use_top_performers": {
                    "type": "boolean",
                    "default": false,
                    "description": "Inject the account's top-performing ads as guidance."
                  },
                  "count": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 20,
                    "default": 1,
                    "description": "Variants to generate. >1 runs an async batch."
                  },
                  "with_landing_page": {
                    "type": "boolean",
                    "default": false,
                    "description": "Also create a matching landing page draft (count=1)."
                  },
                  "page_type": {
                    "type": "string",
                    "enum": [
                      "landing_page",
                      "product_page"
                    ]
                  },
                  "reference_ad_id": {
                    "type": "string",
                    "description": "Remix lineage source ad ID"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generation result (single, combo, or batch)",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "mode": {
                          "type": "string",
                          "enum": [
                            "single"
                          ]
                        },
                        "creative": {
                          "$ref": "#/components/schemas/AdCreative"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "mode": {
                          "type": "string",
                          "enum": [
                            "combo"
                          ]
                        },
                        "creative": {
                          "$ref": "#/components/schemas/AdCreative"
                        },
                        "page_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "mode": {
                          "type": "string",
                          "enum": [
                            "batch"
                          ]
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/social/ads/creatives/status": {
      "get": {
        "summary": "Check ad creative batch status",
        "description": "Poll the status of an async batch ad-creative generation job started via\n`POST /v1/social/ads/creatives` with `count` > 1. Requires any plan (Solo or higher).\n",
        "parameters": [
          {
            "in": "query",
            "name": "request_id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Batch status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "waiting | progress | complete | failed"
                    },
                    "ads": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "total": {
                          "type": "integer"
                        },
                        "completed": {
                          "type": "integer"
                        },
                        "failed": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/social/ads/creatives/{id}": {
      "patch": {
        "summary": "Update, save, or discard an ad creative",
        "description": "Edit copy fields or change the status of an ad creative. Set\n`status: saved` to keep it, `status: discarded` to remove it from the\nlibrary. Requires any plan (Solo or higher).\n",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "headline": {
                    "type": "string",
                    "maxLength": 300,
                    "nullable": true
                  },
                  "primary_text": {
                    "type": "string",
                    "maxLength": 4000,
                    "nullable": true
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 1000,
                    "nullable": true
                  },
                  "cta": {
                    "type": "string",
                    "maxLength": 100,
                    "nullable": true
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "draft",
                      "saved",
                      "discarded"
                    ]
                  },
                  "linked_page_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated creative",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "creative": {
                      "$ref": "#/components/schemas/AdCreative"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/pr/opportunities": {
      "get": {
        "summary": "List PR Radar opportunities",
        "description": "Lists detected PR opportunities (breaking stories the brand can react to)\nwith angles, standing, and source links. Requires any plan (Solo or higher).\n",
        "parameters": [
          {
            "in": "query",
            "name": "site_id",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by site/brand"
          },
          {
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string",
              "enum": [
                "pitch_ready",
                "big_story",
                "watch",
                "dismissed"
              ]
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of opportunities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "opportunities": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "story_title": {
                            "type": "string"
                          },
                          "summary": {
                            "type": "string",
                            "nullable": true
                          },
                          "standing": {
                            "type": "string",
                            "enum": [
                              "strong",
                              "partial",
                              "none"
                            ]
                          },
                          "freshness": {
                            "type": "string",
                            "nullable": true
                          },
                          "source_urls": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "angles": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pitch_ready",
                              "big_story",
                              "watch",
                              "dismissed"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "PR Radar"
        ]
      }
    },
    "/v1/pr/scan": {
      "post": {
        "summary": "Scan for PR opportunities",
        "description": "Scans for breaking/trending stories the brand can credibly comment on. Scans use the team's own Perplexity key. Stores results as opportunities. Requires any plan (Solo or higher). ",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Scan results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "scanned": {
                      "type": "integer"
                    },
                    "inserted": {
                      "type": "integer"
                    },
                    "opportunities": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "PR Radar"
        ]
      }
    },
    "/v1/pr/pitch": {
      "post": {
        "summary": "Generate a PR pitch email",
        "description": "Generates a ready-to-send pitch email for an opportunity, optionally with\nmatched journalists. Requires any plan (Solo or higher).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "opportunity_id"
                ],
                "properties": {
                  "opportunity_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "include_journalists": {
                    "type": "boolean",
                    "description": "Also find relevant journalists to pitch"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Pitch (and optional journalists)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pitch": {
                      "type": "string"
                    },
                    "journalists": {
                      "type": "array",
                      "nullable": true,
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "outlet": {
                            "type": "string"
                          },
                          "beat": {
                            "type": "string"
                          },
                          "contact": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "PR Radar"
        ]
      }
    },
    "/v1/pr/contacts": {
      "get": {
        "summary": "List PR contacts",
        "description": "List durable, per-brand PR contacts (journalists/editors) with email\nverification status. Requires any plan (Solo or higher).\n",
        "parameters": [
          {
            "in": "query",
            "name": "site_id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "query",
            "name": "search",
            "schema": {
              "type": "string"
            },
            "description": "Search name, outlet, or email"
          },
          {
            "in": "query",
            "name": "email_status",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "verified",
                "unverified",
                "valid",
                "risky",
                "catch_all",
                "invalid",
                "unknown"
              ]
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "default": 100
            }
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Contacts list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contacts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PrContact"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "PR Radar"
        ]
      },
      "post": {
        "summary": "Create a PR contact",
        "description": "Manually add a brand PR contact. Requires any plan (Solo or higher).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "name"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string"
                  },
                  "outlet": {
                    "type": "string",
                    "nullable": true
                  },
                  "beat": {
                    "type": "string",
                    "nullable": true
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "nullable": true
                  },
                  "twitter": {
                    "type": "string",
                    "nullable": true
                  },
                  "linkedin": {
                    "type": "string",
                    "nullable": true
                  },
                  "author_url": {
                    "type": "string",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created contact",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contact": {
                      "$ref": "#/components/schemas/PrContact"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "PR Radar"
        ]
      }
    },
    "/v1/pr/contacts/{id}": {
      "delete": {
        "summary": "Delete a PR contact",
        "description": "Delete a brand PR contact by ID. Requires any plan (Solo or higher).",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deletion result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "PR Radar"
        ]
      }
    },
    "/v1/pr/contacts/save-from-opportunity": {
      "post": {
        "summary": "Save journalists from an opportunity",
        "description": "Save the journalists found on an opportunity into the brand contacts list,\ndeduping by email or name + outlet. Requires any plan (Solo or higher).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "opportunity_id"
                ],
                "properties": {
                  "opportunity_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Save summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "created": {
                      "type": "integer"
                    },
                    "merged": {
                      "type": "integer"
                    },
                    "skipped": {
                      "type": "integer"
                    },
                    "contacts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PrContact"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "PR Radar"
        ]
      }
    },
    "/v1/pr/contacts/verify": {
      "post": {
        "summary": "Verify contact emails",
        "description": "Verify the emails on one or more contacts via Kickbox. Included at no charge on every plan. Requires any plan (Solo or higher). ",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "contact_ids"
                ],
                "properties": {
                  "contact_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "maxItems": 50
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verified": {
                      "type": "integer"
                    },
                    "billable": {
                      "type": "integer"
                    },
                    "skipped": {
                      "type": "integer"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "contactId": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "PR Radar"
        ]
      }
    },
    "/v1/social/carousel": {
      "post": {
        "summary": "Generate carousel",
        "description": "Generate a LinkedIn carousel with AI-generated slides. Requires Studio plan or higher.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "topic"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "topic": {
                    "type": "string",
                    "description": "Topic for the carousel"
                  },
                  "hook": {
                    "type": "string",
                    "description": "Opening hook text"
                  },
                  "target_audience": {
                    "type": "string"
                  },
                  "slide_count": {
                    "type": "integer",
                    "minimum": 3,
                    "maximum": 15,
                    "default": 6
                  },
                  "tone": {
                    "type": "string",
                    "enum": [
                      "casual",
                      "professional",
                      "educational",
                      "inspirational"
                    ]
                  },
                  "include_stats": {
                    "type": "boolean"
                  },
                  "cta_text": {
                    "type": "string"
                  },
                  "cta_url": {
                    "type": "string"
                  },
                  "generate_images": {
                    "type": "boolean",
                    "default": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Carousel generated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Carousel data with slides"
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/social/carousel/publish": {
      "post": {
        "summary": "Publish carousel",
        "description": "Publish a carousel to LinkedIn.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "caption",
                  "image_urls"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "caption": {
                    "type": "string"
                  },
                  "image_urls": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "hashtags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "scheduled_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Omit for immediate publishing"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Carousel published",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Publish result"
                }
              }
            }
          }
        },
        "tags": [
          "Social"
        ]
      }
    },
    "/v1/video/script": {
      "post": {
        "summary": "Generate video script",
        "description": "Generate a detailed video prompt and settings from a brief description.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brief"
                ],
                "properties": {
                  "brief": {
                    "type": "string",
                    "description": "Brief description of the video"
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "product_showcase",
                      "lifestyle_aesthetic",
                      "ugc_style",
                      "before_after",
                      "cinematic_broll",
                      "logo_brand_reveal",
                      "tutorial_howto",
                      "testimonial_talking_head",
                      "seasonal_campaign",
                      "abstract_mood"
                    ]
                  },
                  "platform": {
                    "type": "string"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated video script",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "prompt": {
                      "type": "string"
                    },
                    "suggested_duration": {
                      "type": "number"
                    },
                    "suggested_aspect_ratio": {
                      "type": "string"
                    },
                    "suggested_resolution": {
                      "type": "string"
                    },
                    "shot_description": {
                      "type": "string"
                    },
                    "negative_prompt": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Video"
        ]
      }
    },
    "/v1/video": {
      "post": {
        "summary": "Create video generation job",
        "description": "Start a video generation job. Returns an ID to poll for status.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "prompt",
                  "model",
                  "duration_seconds"
                ],
                "properties": {
                  "prompt": {
                    "type": "string"
                  },
                  "model": {
                    "type": "string",
                    "description": "Video model to use. Replicate-hosted models (require Replicate API key):\n`replicate:runway-gen-4.5`, `replicate:seedance-2.0`, `replicate:seedance-2.0-fast`,\n`replicate:kling-v3`, `replicate:veo-3.1-fast`, `replicate:grok-imagine-video`, `replicate:p-video`.\nWaveSpeed-hosted models (require WaveSpeed API key):\n`wavespeed:higgsfield-dop-i2v` (Higgsfield Director-of-Photography image-to-video, REQUIRES `start_image_url`, 5s clips at 720p),\n`wavespeed:wan-2.7` (Alibaba Wan 2.7 text/image/reference/edit/extend, 5-15s, 720p/1080p),\n`wavespeed:wan-3.0` (Alibaba Wan 3.0 text/image/reference, 2-30s, 480p/720p/1080p, native audio).\n",
                    "example": "replicate:runway-gen-4.5"
                  },
                  "duration_seconds": {
                    "type": "number"
                  },
                  "aspect_ratio": {
                    "type": "string",
                    "enum": [
                      "16:9",
                      "9:16",
                      "1:1",
                      "4:3",
                      "3:4",
                      "3:2",
                      "2:3"
                    ]
                  },
                  "resolution": {
                    "type": "string",
                    "enum": [
                      "480p",
                      "720p",
                      "1080p"
                    ]
                  },
                  "negative_prompt": {
                    "type": "string"
                  },
                  "start_image_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Public URL of a still image to use as the first frame. REQUIRED for wavespeed:higgsfield-dop-i2v. Switches Wan 2.7/3.0 to image-to-video. Optional for Seedance, Grok, Kling, Veo, P-Video."
                  },
                  "end_image_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Public URL of a still image to use as the final frame, creating a transition. Supported by Seedance (both), Kling v3, Veo 3.1, Higgsfield DoP, and Wan 2.7/3.0."
                  },
                  "video_mode": {
                    "type": "string",
                    "enum": [
                      "generate",
                      "edit",
                      "extend",
                      "reference"
                    ],
                    "description": "Wan only. generate (default T2V/I2V), reference, edit, or extend. Wan 3.0 edit/extend use reference-to-video."
                  },
                  "source_video_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Public source clip URL. Required for Wan edit/extend."
                  },
                  "reference_image_urls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    },
                    "description": "Wan reference/edit stills."
                  },
                  "reference_video_urls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    },
                    "description": "Wan reference clips. Switches generate mode to reference-to-video."
                  },
                  "reference_audio_urls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    },
                    "description": "Wan 3.0 reference audio."
                  },
                  "generate_audio": {
                    "type": "boolean",
                    "description": "Wan 3.0 native audio. Defaults to true."
                  },
                  "motions": {
                    "type": "array",
                    "description": "WaveSpeed/Higgsfield DoP only. 1-2 camera motions (REQUIRED by the model — defaults to a single \"Zoom Out\" if omitted). Available motions include \"Zoom Out\", \"360 Orbit\", \"3D Rotation\", \"Arc Left\", \"Arc Right\", \"Action Run\", \"Angel Wings\".",
                    "minItems": 1,
                    "maxItems": 2,
                    "items": {
                      "type": "object",
                      "required": [
                        "motion",
                        "strength"
                      ],
                      "properties": {
                        "motion": {
                          "type": "string",
                          "example": "Zoom Out"
                        },
                        "strength": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1,
                          "example": 1
                        }
                      }
                    }
                  },
                  "wavespeed_variant": {
                    "type": "string",
                    "enum": [
                      "dop-lite",
                      "dop-turbo",
                      "dop-preview"
                    ],
                    "description": "WaveSpeed/Higgsfield DoP variant. dop-turbo (default) for balanced speed+quality, dop-lite for drafts, dop-preview for premium."
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "use_brand_context": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Video generation job created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "progress"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Video"
        ]
      }
    },
    "/v1/video/{id}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Video job ID"
        }
      ],
      "get": {
        "summary": "Get video status",
        "description": "Check the status of a video generation job.",
        "responses": {
          "200": {
            "description": "Video job status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "nullable": true
                    },
                    "thumbnail_url": {
                      "type": "string",
                      "nullable": true
                    },
                    "status": {
                      "type": "string"
                    },
                    "provider": {
                      "type": "string",
                      "nullable": true
                    },
                    "model": {
                      "type": "string",
                      "nullable": true
                    },
                    "video_type": {
                      "type": "string",
                      "nullable": true
                    },
                    "meta": {
                      "type": "object",
                      "nullable": true
                    },
                    "progress": {
                      "type": "number",
                      "nullable": true
                    },
                    "duration_seconds": {
                      "type": "number",
                      "nullable": true
                    },
                    "error_message": {
                      "type": "string",
                      "nullable": true
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Video"
        ]
      },
      "delete": {
        "summary": "Delete video",
        "responses": {
          "200": {
            "description": "Video deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Video"
        ]
      }
    },
    "/v1/mood-board": {
      "get": {
        "summary": "List mood boards",
        "parameters": [
          {
            "in": "query",
            "name": "site_id",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by site ID"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of mood boards",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/MoodBoard"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Mood Board"
        ]
      },
      "post": {
        "summary": "Create mood board",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Mood board created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MoodBoard"
                }
              }
            }
          }
        },
        "tags": [
          "Mood Board"
        ]
      }
    },
    "/v1/mood-board/{id}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Mood board ID"
        }
      ],
      "get": {
        "summary": "Get mood board with items",
        "responses": {
          "200": {
            "description": "Mood board with items",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/MoodBoard"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "type": {
                                "type": "string"
                              },
                              "url": {
                                "type": "string",
                                "nullable": true
                              },
                              "metadata": {
                                "type": "object",
                                "nullable": true
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "tags": [
          "Mood Board"
        ]
      },
      "delete": {
        "summary": "Delete mood board",
        "responses": {
          "200": {
            "description": "Mood board deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Mood Board"
        ]
      }
    },
    "/v1/mood-board/generate": {
      "post": {
        "summary": "Generate mood board images",
        "description": "Generate mood board images and colors from brand context. Requires Replicate API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "mood_board_id",
                  "site_id"
                ],
                "properties": {
                  "mood_board_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Generation result with generated images and colors"
                }
              }
            }
          }
        },
        "tags": [
          "Mood Board"
        ]
      }
    },
    "/v1/links": {
      "get": {
        "summary": "List Link Engine sites",
        "description": "Returns sites with Link Engine configuration. Requires any plan (Solo 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"
        ]
      }
    },
    "/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"
        ]
      }
    },
    "/v1/links/{id}/config": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Site ID"
        }
      ],
      "get": {
        "summary": "Get Link Engine settings",
        "description": "Internal/external link counts, strategy, and allowed domains.",
        "responses": {
          "200": {
            "description": "Link Engine config"
          }
        },
        "tags": [
          "Links"
        ]
      },
      "patch": {
        "summary": "Update Link Engine settings",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "max_internal_links": {
                    "type": "integer"
                  },
                  "max_external_links": {
                    "type": "integer"
                  },
                  "max_links_per_section": {
                    "type": "integer"
                  },
                  "min_similarity_score": {
                    "type": "number"
                  },
                  "linking_strategy": {
                    "type": "string",
                    "enum": [
                      "semantic",
                      "contextual",
                      "topical",
                      "hybrid"
                    ]
                  },
                  "add_external_domains": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "remove_external_domains": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "block_external_domains": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Link Engine config updated"
          }
        },
        "tags": [
          "Links"
        ]
      }
    },
    "/v1/links/{id}/external": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Site ID"
        }
      ],
      "post": {
        "summary": "Add a trusted external URL",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "External source added"
          }
        },
        "tags": [
          "Links"
        ]
      }
    },
    "/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": {
        "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"
        ]
      }
    },
    "/v1/links/inject": {
      "post": {
        "summary": "Run Link Engine on articles",
        "description": "Inject internal and/or external links into a batch of completed articles.\nReturns a request_id for polling status via GET. Up to 500 articles per call.\nArticles must belong to the authenticated team and have status \"complete\".\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "article_ids",
                  "site_id"
                ],
                "properties": {
                  "article_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "minItems": 1,
                    "maxItems": 500,
                    "description": "Article IDs to inject links into"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Site ID (must have Link Engine configured)"
                  },
                  "max_links_per_article": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 20,
                    "default": 5,
                    "description": "Maximum links to inject per article"
                  },
                  "include_internal": {
                    "type": "boolean",
                    "default": true,
                    "description": "Include internal links"
                  },
                  "include_external": {
                    "type": "boolean",
                    "default": true,
                    "description": "Include external links"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Link injection job created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "total_articles": {
                      "type": "integer"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "waiting"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or Link Engine not configured"
          },
          "403": {
            "description": "Plan does not support Link Engine"
          }
        },
        "tags": [
          "Links"
        ]
      },
      "get": {
        "summary": "Get link injection status",
        "description": "Poll the status of a link injection job.",
        "parameters": [
          {
            "in": "query",
            "name": "request_id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Request ID from POST /v1/links/inject"
          },
          {
            "in": "query",
            "name": "page",
            "schema": {
              "type": "integer",
              "default": 1
            },
            "description": "Page for per-article status"
          }
        ],
        "responses": {
          "200": {
            "description": "Link injection job status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "request_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "waiting",
                        "progress",
                        "complete",
                        "failed",
                        "canceled"
                      ]
                    },
                    "total_articles": {
                      "type": "integer"
                    },
                    "completed_articles": {
                      "type": "integer"
                    },
                    "failed_articles": {
                      "type": "integer"
                    },
                    "total_links_added": {
                      "type": "integer"
                    },
                    "articles": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "object",
                        "properties": {
                          "status": {
                            "type": "string"
                          },
                          "linksAdded": {
                            "type": "integer"
                          },
                          "error": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "page_size": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Job not found"
          }
        },
        "tags": [
          "Links"
        ]
      }
    },
    "/v1/templates": {
      "get": {
        "summary": "List custom templates",
        "description": "List all custom templates for the team. Requires Studio plan or higher.",
        "parameters": [
          {
            "in": "query",
            "name": "page",
            "schema": {
              "type": "integer"
            },
            "description": "Page number for pagination"
          },
          {
            "in": "query",
            "name": "site_id",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by site ID"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of custom templates",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/TemplateListItem"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Templates"
        ]
      },
      "post": {
        "summary": "Create a custom template",
        "description": "Create a new custom template. Requires Studio plan or higher.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "system_prompt",
                  "user_prompt"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "system_prompt": {
                    "type": "string"
                  },
                  "user_prompt": {
                    "type": "string"
                  },
                  "ideal_output": {
                    "type": "string"
                  },
                  "variables": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "enable_knowledge": {
                    "type": "boolean",
                    "default": false
                  },
                  "enable_serp": {
                    "type": "boolean",
                    "default": false
                  },
                  "enable_perplexity": {
                    "type": "boolean",
                    "default": false
                  },
                  "include_faq": {
                    "type": "boolean",
                    "default": false
                  },
                  "include_key_takeaways": {
                    "type": "boolean",
                    "default": false
                  },
                  "include_toc": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Template created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplateDetail"
                }
              }
            }
          }
        },
        "tags": [
          "Templates"
        ]
      }
    },
    "/v1/templates/{id}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Template ID"
        }
      ],
      "get": {
        "summary": "Get a custom template",
        "description": "Get template details including prompts and configuration.",
        "responses": {
          "200": {
            "description": "Template detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplateDetail"
                }
              }
            }
          }
        },
        "tags": [
          "Templates"
        ]
      },
      "put": {
        "summary": "Update a custom template",
        "description": "Update an existing custom template. Only provided fields are updated.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "system_prompt": {
                    "type": "string"
                  },
                  "user_prompt": {
                    "type": "string"
                  },
                  "ideal_output": {
                    "type": "string"
                  },
                  "variables": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "enable_knowledge": {
                    "type": "boolean"
                  },
                  "enable_serp": {
                    "type": "boolean"
                  },
                  "enable_perplexity": {
                    "type": "boolean"
                  },
                  "include_faq": {
                    "type": "boolean"
                  },
                  "include_key_takeaways": {
                    "type": "boolean"
                  },
                  "include_toc": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Template updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplateDetail"
                }
              }
            }
          }
        },
        "tags": [
          "Templates"
        ]
      },
      "delete": {
        "summary": "Delete a custom template",
        "responses": {
          "204": {
            "description": "Template deleted"
          }
        },
        "tags": [
          "Templates"
        ]
      }
    },
    "/v1/knowledge/{id}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "integer"
          },
          "description": "Knowledge source ID"
        }
      ],
      "get": {
        "summary": "Get a knowledge source",
        "description": "Get a single knowledge source by ID. Requires any plan (Solo or higher).",
        "responses": {
          "200": {
            "description": "Knowledge source detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeSource"
                }
              }
            }
          }
        },
        "tags": [
          "Knowledge"
        ]
      },
      "patch": {
        "summary": "Update a knowledge source",
        "description": "Update knowledge source metadata (name, description, etc.). Requires any plan (Solo or higher).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string",
                    "nullable": true
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                  },
                  "enabled": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Knowledge source updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeSource"
                }
              }
            }
          }
        },
        "tags": [
          "Knowledge"
        ]
      },
      "delete": {
        "summary": "Delete a knowledge source",
        "description": "Delete a knowledge source and its embeddings. Requires any plan (Solo or higher).",
        "responses": {
          "204": {
            "description": "Knowledge source deleted"
          }
        },
        "tags": [
          "Knowledge"
        ]
      }
    },
    "/v1/skills": {
      "get": {
        "summary": "List Brand Skills",
        "description": "Returns the team's Brand Skills (procedural playbooks). Optionally scope to a\nsite with `site_id`; site scope also includes team-wide skills.\nRequires any plan (Solo or higher).\n",
        "parameters": [
          {
            "in": "query",
            "name": "site_id",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Scope results to a site (includes team-wide skills)"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of Brand Skills",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/BrandSkill"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Skills"
        ]
      },
      "post": {
        "summary": "Create a Brand Skill",
        "description": "Create a Brand Skill manually from a name, description, and markdown body.\nContent is validated for prompt-injection patterns and size limits.\nRequires any plan (Solo or higher).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "description",
                  "content"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 1024
                  },
                  "content": {
                    "type": "string",
                    "description": "Markdown body of the skill (the SKILL.md content)"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true,
                    "description": "Attach to a site; omit for a team-wide skill"
                  },
                  "team_visible": {
                    "type": "boolean"
                  },
                  "applies_to": {
                    "type": "array",
                    "description": "Surfaces this skill applies to. Defaults to [\"text\"]. Use [\"text\",\"image\",\"video\"] for a brand-wide skill.",
                    "items": {
                      "type": "string",
                      "enum": [
                        "text",
                        "image",
                        "video"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Brand Skill created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandSkill"
                }
              }
            }
          }
        },
        "tags": [
          "Skills"
        ]
      }
    },
    "/v1/skills/{id}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "integer"
          },
          "description": "Brand Skill ID"
        }
      ],
      "get": {
        "summary": "Get a Brand Skill",
        "description": "Get a single Brand Skill by ID. Requires any plan (Solo or higher).",
        "responses": {
          "200": {
            "description": "Brand Skill detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandSkill"
                }
              }
            }
          }
        },
        "tags": [
          "Skills"
        ]
      },
      "patch": {
        "summary": "Update a Brand Skill",
        "description": "Update a Brand Skill's editable fields. Changing name/description/content\nre-runs content validation. Requires any plan (Solo or higher).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 1024,
                    "nullable": true
                  },
                  "content": {
                    "type": "string"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                  },
                  "enabled": {
                    "type": "boolean"
                  },
                  "team_visible": {
                    "type": "boolean"
                  },
                  "applies_to": {
                    "type": "array",
                    "description": "Surfaces this skill applies to (text, image, video).",
                    "items": {
                      "type": "string",
                      "enum": [
                        "text",
                        "image",
                        "video"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Brand Skill updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandSkill"
                }
              }
            }
          }
        },
        "tags": [
          "Skills"
        ]
      },
      "delete": {
        "summary": "Delete a Brand Skill",
        "description": "Delete a Brand Skill and its bundled files. Requires any plan (Solo or higher).",
        "responses": {
          "204": {
            "description": "Brand Skill deleted"
          }
        },
        "tags": [
          "Skills"
        ]
      }
    },
    "/v1/skills/import/github": {
      "post": {
        "summary": "Import Brand Skills from GitHub",
        "description": "Import skills from a public GitHub repository. Without `selected_paths` this\nreturns a preview of discovered SKILL.md files (pinned to the latest commit\nSHA). With `selected_paths` it installs those skills as immutable snapshots.\nPublic repositories only. Requires any plan (Solo or higher).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "GitHub repo URL or owner/repo (optionally with a path)"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                  },
                  "selected_paths": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "SKILL.md paths from the preview to install"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Preview of discovered skills, or install result"
          }
        },
        "tags": [
          "Skills"
        ]
      }
    },
    "/v1/sites/{id}/brand/context": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Site ID"
        }
      ],
      "get": {
        "summary": "Get brand context",
        "description": "Returns brand context (company info, competitors, keywords, etc.)",
        "responses": {
          "200": {
            "description": "Brand context",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandContext"
                }
              }
            }
          }
        },
        "tags": [
          "Sites"
        ]
      },
      "patch": {
        "summary": "Update brand context",
        "description": "Update editable brand context fields. Creates context if it doesn't exist.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "tagline": {
                    "type": "string"
                  },
                  "industry": {
                    "type": "string"
                  },
                  "target_audience": {
                    "type": "string"
                  },
                  "value_proposition": {
                    "type": "string"
                  },
                  "differentiators": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "pain_points": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "add_competitors": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "domain": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "remove_competitors": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "set_competitors": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "domain": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Brand context updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandContext"
                }
              }
            }
          }
        },
        "tags": [
          "Sites"
        ]
      }
    },
    "/v1/sites/{id}/brand/visual-style": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Site ID"
        }
      ],
      "get": {
        "summary": "Get brand visual style",
        "description": "Returns brand visual style (colors, fonts, logo, etc.)",
        "responses": {
          "200": {
            "description": "Brand visual style",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandVisualStyle"
                }
              }
            }
          }
        },
        "tags": [
          "Sites"
        ]
      },
      "put": {
        "summary": "Update brand visual style",
        "description": "Update brand visual style. Only provided fields are updated.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "logo_url": {
                    "type": "string"
                  },
                  "primary_color": {
                    "type": "string"
                  },
                  "secondary_color": {
                    "type": "string"
                  },
                  "accent_color": {
                    "type": "string"
                  },
                  "primary_font": {
                    "type": "string"
                  },
                  "secondary_font": {
                    "type": "string"
                  },
                  "visual_mood": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Brand visual style updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandVisualStyle"
                }
              }
            }
          }
        },
        "tags": [
          "Sites"
        ]
      }
    },
    "/v1/sites/{id}/brand/voices": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Site ID"
        }
      ],
      "get": {
        "summary": "Get brand voices",
        "description": "Returns brand voices (tone, persona, formality, etc.)",
        "responses": {
          "200": {
            "description": "List of brand voices",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/BrandVoice"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Sites"
        ]
      },
      "patch": {
        "summary": "Update or create the active brand voice",
        "description": "Updates the active voice, or creates one if none exists.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "tone": {
                    "type": "string"
                  },
                  "persona": {
                    "type": "string"
                  },
                  "formality": {
                    "type": "string"
                  },
                  "vocabulary": {
                    "type": "string"
                  },
                  "sentence_structure": {
                    "type": "string"
                  },
                  "summary": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Brand voice updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandVoice"
                }
              }
            }
          }
        },
        "tags": [
          "Sites"
        ]
      }
    },
    "/v1/sites/{id}/automations": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Site ID"
        }
      ],
      "get": {
        "summary": "List Brand Room automations",
        "description": "Returns Brand Room automations for a site (max 5).",
        "responses": {
          "200": {
            "description": "Automations for the site",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "automations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BrandAutomation"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Automations"
        ]
      },
      "post": {
        "summary": "Create or update a Brand Room automation",
        "description": "Upserts the automation bound to a chat (one per chat). Requires an\nexisting chat_id. Site in the URL must match the chat's site when set.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBrandAutomation"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Automation saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandAutomation"
                }
              }
            }
          },
          "409": {
            "description": "Another run is already in progress"
          }
        },
        "tags": [
          "Automations"
        ]
      }
    },
    "/v1/automations/{id}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Automation ID"
        }
      ],
      "get": {
        "summary": "Get a Brand Room automation",
        "responses": {
          "200": {
            "description": "Automation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandAutomation"
                }
              }
            }
          }
        },
        "tags": [
          "Automations"
        ]
      },
      "patch": {
        "summary": "Update a Brand Room automation",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateBrandAutomation"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Automation updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandAutomation"
                }
              }
            }
          }
        },
        "tags": [
          "Automations"
        ]
      },
      "delete": {
        "summary": "Delete a Brand Room automation",
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Automations"
        ]
      }
    },
    "/v1/automations/{id}/run": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Automation ID"
        }
      ],
      "post": {
        "summary": "Run a Brand Room automation now",
        "description": "Enqueues brand-automation/run. Returns 409 if a run is already in progress.",
        "responses": {
          "200": {
            "description": "Queued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "queued": {
                      "type": "boolean"
                    },
                    "automation": {
                      "$ref": "#/components/schemas/BrandAutomation"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Another run is already in progress"
          }
        },
        "tags": [
          "Automations"
        ]
      }
    },
    "/v1/notifications/preferences": {
      "get": {
        "summary": "Get notification preferences",
        "description": "Team email and Slack preferences, including Brand Room events.",
        "responses": {
          "200": {
            "description": "Preferences",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationPreferences"
                }
              }
            }
          }
        },
        "tags": [
          "Notifications"
        ]
      },
      "patch": {
        "summary": "Update notification preferences",
        "description": "Flip email or Slack for a single event, or pass updates[] for a batch.\nBrand Room events: chat.mentioned, chat.agent_completed,\nautomation.completed.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "required": [
                      "channel",
                      "event_type",
                      "enabled"
                    ],
                    "properties": {
                      "channel": {
                        "type": "string",
                        "enum": [
                          "email",
                          "slack"
                        ]
                      },
                      "event_type": {
                        "type": "string"
                      },
                      "enabled": {
                        "type": "boolean"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "updates"
                    ],
                    "properties": {
                      "updates": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "required": [
                            "channel",
                            "event_type",
                            "enabled"
                          ],
                          "properties": {
                            "channel": {
                              "type": "string",
                              "enum": [
                                "email",
                                "slack"
                              ]
                            },
                            "event_type": {
                              "type": "string"
                            },
                            "enabled": {
                              "type": "boolean"
                            }
                          }
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated preferences",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationPreferences"
                }
              }
            }
          }
        },
        "tags": [
          "Notifications"
        ]
      }
    },
    "/v1/notifications/send": {
      "post": {
        "summary": "Send a team notification now",
        "description": "Fire email or Slack now via the existing dispatcher. Plain text only\n(HTML is stripped). Recipients are team members who opted in, or\nexplicit user_ids on the team.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendNotification"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Send result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sent": {
                      "type": "boolean"
                    },
                    "channel": {
                      "type": "string",
                      "enum": [
                        "email",
                        "slack"
                      ]
                    },
                    "recipient_count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Notifications"
        ]
      }
    },
    "/v1/sites/{id}/content-strategy": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Site ID"
        }
      ],
      "get": {
        "summary": "Get content strategy settings",
        "description": "Returns the content strategy settings for a site including article\ndefaults, social publishing config, newsletter settings, and\nautomation rules. Requires Solo plan or higher.\n",
        "responses": {
          "200": {
            "description": "Content strategy settings",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentStrategySettings"
                }
              }
            }
          }
        },
        "tags": [
          "Sites"
        ]
      },
      "put": {
        "summary": "Update content strategy settings",
        "description": "Update content strategy settings for a site. Supports partial\nupdates: only send the sections you want to change. Requires\nSolo plan or higher.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContentStrategySettings"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated content strategy settings",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentStrategySettings"
                }
              }
            }
          }
        },
        "tags": [
          "Sites"
        ]
      }
    },
    "/v1/brands/{siteId}/notebook": {
      "parameters": [
        {
          "in": "path",
          "name": "siteId",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Site ID"
        }
      ],
      "get": {
        "summary": "List notebook entries",
        "description": "List client notes / meeting transcripts for a site. Requires Scale plan or higher.",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "in": "query",
            "name": "source",
            "schema": {
              "type": "string"
            },
            "description": "Filter by source (api, manual, etc.)"
          }
        ],
        "responses": {
          "200": {
            "description": "List of notebook entries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/NotebookEntry"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Brand Notebook"
        ]
      },
      "post": {
        "summary": "Create a notebook entry",
        "description": "Add a new client note or meeting transcript. Content is automatically indexed for RAG.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title",
                  "content"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "content": {
                    "type": "string",
                    "maxLength": 100000
                  },
                  "meeting_date": {
                    "type": "string",
                    "format": "date",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Entry created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotebookEntry"
                }
              }
            }
          }
        },
        "tags": [
          "Brand Notebook"
        ]
      }
    },
    "/v1/brands/{siteId}/notebook/{entryId}": {
      "parameters": [
        {
          "in": "path",
          "name": "siteId",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        {
          "in": "path",
          "name": "entryId",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Get a notebook entry",
        "responses": {
          "200": {
            "description": "Notebook entry detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotebookEntry"
                }
              }
            }
          }
        },
        "tags": [
          "Brand Notebook"
        ]
      },
      "put": {
        "summary": "Update a notebook entry",
        "description": "Update an existing notebook entry. If content changes, it is re-indexed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "content": {
                    "type": "string",
                    "maxLength": 100000
                  },
                  "meeting_date": {
                    "type": "string",
                    "format": "date",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Entry updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotebookEntry"
                }
              }
            }
          }
        },
        "tags": [
          "Brand Notebook"
        ]
      },
      "delete": {
        "summary": "Delete a notebook entry",
        "responses": {
          "204": {
            "description": "Entry deleted"
          }
        },
        "tags": [
          "Brand Notebook"
        ]
      }
    },
    "/v1/agents": {
      "get": {
        "summary": "List research agents",
        "description": "List all research agents for the team. Requires any plan (Solo or higher).",
        "parameters": [
          {
            "in": "query",
            "name": "site_id",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by site ID"
          }
        ],
        "responses": {
          "200": {
            "description": "List of agents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Agent"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Agents"
        ]
      }
    },
    "/v1/agents/{id}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Agent ID"
        }
      ],
      "get": {
        "summary": "Get an agent",
        "description": "Get agent details including latest snapshot and research brief.",
        "responses": {
          "200": {
            "description": "Agent detail with latest results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentDetail"
                }
              }
            }
          }
        },
        "tags": [
          "Agents"
        ]
      }
    },
    "/v1/agents/{id}/run": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "summary": "Trigger an agent run",
        "description": "Manually trigger an agent to run immediately. Returns 409 if already running.",
        "responses": {
          "200": {
            "description": "Agent run triggered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Agent is already running"
          }
        },
        "tags": [
          "Agents"
        ]
      }
    },
    "/v1/pages": {
      "post": {
        "summary": "Create a page",
        "description": "Generate a landing page, product page, comparison, or alternatives page. Returns a page ID immediately. Poll GET /v1/pages/{id} until status is 'complete'.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "target_keyword"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Brand / site ID"
                  },
                  "target_keyword": {
                    "type": "string",
                    "description": "Primary keyword for the page"
                  },
                  "page_type": {
                    "type": "string",
                    "enum": [
                      "landing_page",
                      "product_page",
                      "comparison",
                      "alternatives"
                    ],
                    "default": "landing_page"
                  },
                  "title": {
                    "type": "string",
                    "description": "Optional title; otherwise derived from keyword"
                  },
                  "model": {
                    "type": "string",
                    "description": "AI model to use for generation. Defaults to gpt-6-luna. Examples - gpt-6.2-astra, gpt-6.2-sol, gpt-6-luna, claude-fable-5-2, claude-opus-5-5, claude-sonnet-5, grok-4.7, gemini-3.5-flash. Use the `/v1/meta/models` endpoint for the full list."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Page created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          }
        },
        "tags": [
          "Pages"
        ]
      },
      "get": {
        "summary": "List pages",
        "description": "Returns all pages for the team, optionally filtered by site.",
        "parameters": [
          {
            "in": "query",
            "name": "site_id",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by site ID"
          },
          {
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "generating",
                "complete",
                "error"
              ]
            },
            "description": "Filter by status"
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of pages",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Page"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Pages"
        ]
      }
    },
    "/v1/pages/{id}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Get page by ID",
        "description": "Returns full page details including sections, meta, and schema markup.",
        "parameters": [
          {
            "in": "query",
            "name": "site_id",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/Page"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "schema_markup": {
                              "type": "array",
                              "items": {
                                "type": "object"
                              },
                              "description": "JSON-LD schema objects (WebPage, FAQPage, Product)"
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Page not found"
          }
        },
        "tags": [
          "Pages"
        ]
      }
    },
    "/v1/pages/{id}/status": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Get page generation status",
        "description": "Quick status check for a page (draft, generating, complete, error).",
        "responses": {
          "200": {
            "description": "Page status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Page not found"
          }
        },
        "tags": [
          "Pages"
        ]
      }
    },
    "/v1/research/serp-cluster-bulk": {
      "post": {
        "summary": "Bulk SERP clustering with site assignment",
        "description": "Submit a large batch of keywords (15K-60K) for SERP-based clustering and automatic site assignment.\nKeywords are clustered by URL overlap, then assigned to sites based on category matching from an Airtable source.\nResults are written to an Airtable output table.\n\nThis is an async operation. Use the returned job_id to poll for status.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_source",
                  "output"
                ],
                "properties": {
                  "keywords_csv": {
                    "type": "string",
                    "description": "Raw CSV content (Ahrefs/SEMrush format). Either this or keywords array is required."
                  },
                  "keywords": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "keyword",
                        "volume",
                        "kd"
                      ],
                      "properties": {
                        "keyword": {
                          "type": "string"
                        },
                        "volume": {
                          "type": "number"
                        },
                        "kd": {
                          "type": "number"
                        }
                      }
                    },
                    "description": "Array of keywords with volume and KD. Either this or keywords_csv is required."
                  },
                  "config": {
                    "type": "object",
                    "description": "Filter thresholds. Defaults are very permissive since customers typically pre-filter in Ahrefs.",
                    "properties": {
                      "max_kd": {
                        "type": "number",
                        "default": 100,
                        "description": "Max keyword difficulty (0-100). Set lower to filter."
                      },
                      "min_volume": {
                        "type": "number",
                        "default": 0,
                        "description": "Min search volume. Set higher to filter."
                      },
                      "max_volume": {
                        "type": "number",
                        "default": 999999,
                        "description": "Max search volume. Set lower to filter."
                      },
                      "overlap_threshold": {
                        "type": "number",
                        "default": 0.3
                      },
                      "serp_depth": {
                        "type": "number",
                        "default": 10
                      },
                      "location_code": {
                        "type": "number",
                        "default": 2840
                      },
                      "language_code": {
                        "type": "string",
                        "default": "en"
                      }
                    }
                  },
                  "assignment": {
                    "type": "object",
                    "description": "Controls how clusters are distributed across sites",
                    "properties": {
                      "priority_sites": {
                        "type": "array",
                        "description": "Sites that should receive a scoring boost during assignment",
                        "items": {
                          "type": "object",
                          "required": [
                            "domain"
                          ],
                          "properties": {
                            "domain": {
                              "type": "string",
                              "description": "Site domain to boost"
                            },
                            "boost": {
                              "type": "number",
                              "default": 2,
                              "description": "Score multiplier (1-10). Higher means more likely to win clusters."
                            }
                          }
                        }
                      },
                      "max_clusters_per_site": {
                        "type": "number",
                        "description": "Max clusters any single site can receive per run (velocity cap). Unset means no limit."
                      },
                      "min_clusters_per_site": {
                        "type": "number",
                        "description": "Minimum clusters each site should receive. Unassigned clusters are redistributed to sites below this floor using a 4-tier matching cascade (subcategory, category token, keyword overlap, round-robin). Unset means no floor."
                      },
                      "scarcity_strength": {
                        "type": "number",
                        "default": 1,
                        "description": "Controls distribution spread. 0 = pure relevance (best-match site always wins), 1 = balanced (default), 2-3 = aggressive spread (empty sites get stronger boost)."
                      }
                    }
                  },
                  "site_source": {
                    "type": "object",
                    "required": [
                      "airtable_base_id",
                      "airtable_table_name",
                      "columns"
                    ],
                    "properties": {
                      "airtable_base_id": {
                        "type": "string"
                      },
                      "airtable_table_name": {
                        "type": "string"
                      },
                      "columns": {
                        "type": "object",
                        "required": [
                          "website",
                          "categories",
                          "subcategories"
                        ],
                        "properties": {
                          "website": {
                            "type": "string"
                          },
                          "site_name": {
                            "type": "string"
                          },
                          "categories": {
                            "type": "string"
                          },
                          "subcategories": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  },
                  "output": {
                    "type": "object",
                    "required": [
                      "airtable_base_id",
                      "airtable_table_name"
                    ],
                    "properties": {
                      "airtable_base_id": {
                        "type": "string"
                      },
                      "airtable_table_name": {
                        "type": "string"
                      },
                      "clear_before_write": {
                        "type": "boolean",
                        "default": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Job created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string"
                    },
                    "estimated_time_minutes": {
                      "type": "number"
                    },
                    "estimated_cost": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        },
        "tags": [
          "Research"
        ]
      }
    },
    "/v1/research/serp-cluster-bulk/{jobId}": {
      "parameters": [
        {
          "in": "path",
          "name": "jobId",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Get cluster bulk job status",
        "description": "Poll for the status of a bulk SERP clustering job. Returns progress info and summary when complete.",
        "responses": {
          "200": {
            "description": "Job status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending",
                        "parsing",
                        "fetching_serps",
                        "clustering",
                        "reading_sites",
                        "assigning",
                        "writing_results",
                        "completed",
                        "failed"
                      ]
                    },
                    "progress": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "current": {
                          "type": "number"
                        },
                        "total": {
                          "type": "number"
                        }
                      }
                    },
                    "message": {
                      "type": "string",
                      "nullable": true
                    },
                    "summary": {
                      "type": "object",
                      "nullable": true,
                      "description": "Available when status is completed"
                    },
                    "error": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Job not found"
          }
        },
        "tags": [
          "Research"
        ]
      }
    },
    "/v1/research/serp-cluster-bulk/{jobId}/generate": {
      "parameters": [
        {
          "in": "path",
          "name": "jobId",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "summary": "Generate articles from approved clusters",
        "description": "Reads rows from the Airtable output table, creates articles in Cuppa, and dispatches generation.\nBy default only rows with Status = Assigned AND the Approved checkbox = true are included.\nArticles appear in the Cuppa UI under the correct site. Status is written back to Airtable.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "settings"
                ],
                "properties": {
                  "filter": {
                    "type": "object",
                    "properties": {
                      "status": {
                        "type": "string",
                        "default": "Assigned",
                        "description": "Must match clustering output single-select (usually Assigned)"
                      },
                      "require_approved_checkbox": {
                        "type": "boolean",
                        "default": true,
                        "description": "When true, require Approved checkbox. Set false for legacy Status-only tables."
                      },
                      "approved_checkbox_field": {
                        "type": "string",
                        "default": "Approved"
                      },
                      "airtable_filter_formula": {
                        "type": "string",
                        "description": "Full Airtable filterByFormula; overrides status and checkbox logic"
                      },
                      "sites": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "max_articles": {
                        "type": "number"
                      }
                    }
                  },
                  "settings": {
                    "type": "object",
                    "required": [
                      "language",
                      "region"
                    ],
                    "properties": {
                      "language": {
                        "type": "string"
                      },
                      "region": {
                        "type": "string"
                      },
                      "model": {
                        "type": "string"
                      },
                      "tone": {
                        "type": "string"
                      },
                      "pov": {
                        "type": "string"
                      },
                      "generate_images": {
                        "type": "boolean",
                        "default": false
                      },
                      "include_introduction": {
                        "type": "boolean",
                        "default": true
                      },
                      "include_conclusion": {
                        "type": "boolean",
                        "default": true
                      }
                    }
                  },
                  "airtable_status_column": {
                    "type": "string",
                    "description": "Column name in Airtable to write generation status updates"
                  },
                  "cuppa_article_id_field": {
                    "type": "string",
                    "default": "Cuppa Article ID",
                    "description": "Airtable column for article UUID; must match filter and write-back"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Generation job created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string"
                    },
                    "articles_queued": {
                      "type": "number"
                    },
                    "sites_involved": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Cluster job not complete or invalid request"
          },
          "404": {
            "description": "Cluster job not found"
          }
        },
        "tags": [
          "Research"
        ]
      }
    },
    "/v1/integrations/vercel": {
      "get": {
        "summary": "List Vercel projects and brand links",
        "responses": {
          "200": {
            "description": "Projects and links"
          }
        },
        "tags": [
          "Integrations"
        ]
      },
      "post": {
        "summary": "Manage the Vercel integration",
        "description": "Actions are connect, link, unlink, deploy, deploy_status, and disconnect.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "action"
                ],
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "connect",
                      "link",
                      "unlink",
                      "deploy",
                      "deploy_status",
                      "disconnect"
                    ]
                  },
                  "access_token": {
                    "type": "string"
                  },
                  "brand_site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "project_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Vercel operation result"
          }
        },
        "tags": [
          "Integrations"
        ]
      }
    },
    "/v1/integrations/astro": {
      "get": {
        "summary": "Get Astro connection status",
        "parameters": [
          {
            "in": "query",
            "name": "brand_site_id",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Astro status"
          }
        },
        "tags": [
          "Integrations"
        ]
      },
      "post": {
        "summary": "Manage an Astro connection",
        "description": "Actions are connect, rotate_token, disconnect, and status.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "action",
                  "brand_site_id"
                ],
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "connect",
                      "rotate_token",
                      "disconnect",
                      "status"
                    ]
                  },
                  "brand_site_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Astro operation result"
          }
        },
        "tags": [
          "Integrations"
        ]
      }
    },
    "/v1/pages/{id}/publish": {
      "post": {
        "summary": "Publish or unpublish a page to Astro and Vercel",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "platform"
                ],
                "properties": {
                  "platform": {
                    "type": "string",
                    "enum": [
                      "astro",
                      "vercel"
                    ]
                  },
                  "unpublish": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Publish and deployment status"
          }
        },
        "tags": [
          "Pages"
        ]
      }
    },
    "/v1/astro/contents": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "List published articles for an Astro site token",
        "responses": {
          "200": {
            "description": "Published article collection"
          }
        },
        "tags": [
          "Astro"
        ]
      }
    },
    "/v1/astro/pages": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "List published pages for an Astro site token",
        "responses": {
          "200": {
            "description": "Published page collection"
          }
        },
        "tags": [
          "Astro"
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "CPA_SITE_"
      }
    },
    "responses": {},
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "status": {
                "type": "number"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "AdCreative": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "site_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "source": {
            "type": "string",
            "description": "generated | imported"
          },
          "platform": {
            "type": "string",
            "nullable": true
          },
          "format": {
            "type": "string",
            "nullable": true
          },
          "headline": {
            "type": "string",
            "nullable": true
          },
          "primary_text": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "cta": {
            "type": "string",
            "nullable": true
          },
          "image_url": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "description": "draft | saved | discarded"
          },
          "batch_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "linked_page_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Matching landing page draft (combo generation)"
          },
          "reference_ad_id": {
            "type": "string",
            "nullable": true,
            "description": "Remix lineage source ad ID"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PrContact": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "site_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "outlet": {
            "type": "string",
            "nullable": true
          },
          "beat": {
            "type": "string",
            "nullable": true
          },
          "email": {
            "type": "string",
            "nullable": true
          },
          "twitter": {
            "type": "string",
            "nullable": true
          },
          "linkedin": {
            "type": "string",
            "nullable": true
          },
          "author_url": {
            "type": "string",
            "nullable": true
          },
          "email_status": {
            "type": "string",
            "enum": [
              "unverified",
              "valid",
              "risky",
              "catch_all",
              "invalid",
              "unknown"
            ]
          },
          "email_verified_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "verification_provider": {
            "type": "string",
            "nullable": true
          },
          "source": {
            "type": "string"
          },
          "source_opportunity_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TaskStatus": {
        "type": "string",
        "enum": [
          "initializing",
          "waiting",
          "progress",
          "canceled",
          "complete",
          "failed"
        ]
      },
      "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}."
          }
        }
      },
      "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
          }
        }
      },
      "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"
              }
            }
          }
        }
      },
      "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-2",
                "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
          }
        }
      },
      "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\")"
          }
        }
      },
      "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
          }
        }
      },
      "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.)"
          }
        }
      },
      "BrandAutomation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "team_id": {
            "type": "string",
            "format": "uuid"
          },
          "site_id": {
            "type": "string",
            "format": "uuid"
          },
          "chat_id": {
            "type": "string",
            "format": "uuid"
          },
          "created_by": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "name": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "mode": {
            "type": "string"
          },
          "schedule": {
            "type": "string",
            "enum": [
              "daily",
              "weekly",
              "monthly",
              "manual"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "paused",
              "error",
              "running"
            ]
          },
          "last_run_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "next_run_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "last_error": {
            "type": "string",
            "nullable": true
          },
          "run_by": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CreateBrandAutomation": {
        "type": "object",
        "required": [
          "chat_id",
          "name",
          "prompt",
          "model",
          "schedule"
        ],
        "properties": {
          "chat_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "mode": {
            "type": "string"
          },
          "schedule": {
            "type": "string",
            "enum": [
              "daily",
              "weekly",
              "monthly",
              "manual"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "paused"
            ]
          }
        }
      },
      "UpdateBrandAutomation": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "mode": {
            "type": "string"
          },
          "schedule": {
            "type": "string",
            "enum": [
              "daily",
              "weekly",
              "monthly",
              "manual"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "paused"
            ]
          }
        }
      },
      "NotificationPreferences": {
        "type": "object",
        "properties": {
          "preferences": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "email": {
                  "type": "boolean"
                },
                "slack": {
                  "type": "boolean"
                }
              }
            }
          },
          "slack_connected": {
            "type": "boolean"
          }
        }
      },
      "SendNotification": {
        "type": "object",
        "required": [
          "channel",
          "message"
        ],
        "properties": {
          "channel": {
            "type": "string",
            "enum": [
              "email",
              "slack"
            ]
          },
          "event": {
            "type": "string"
          },
          "message": {
            "type": "string",
            "maxLength": 2000
          },
          "site_id": {
            "type": "string",
            "format": "uuid"
          },
          "user_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          }
        }
      },
      "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
          }
        }
      },
      "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"
              }
            }
          }
        }
      },
      "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
          }
        }
      },
      "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-2, 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"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "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"
                }
              }
            }
          }
        }
      },
      "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
          }
        }
      },
      "BrandSkill": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "slug": {
            "type": "string",
            "description": "Slug used to reference the skill (e.g. seo-audit)"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "enabled": {
            "type": "boolean"
          },
          "team_visible": {
            "type": "boolean"
          },
          "site_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "source": {
            "type": "string",
            "enum": [
              "github",
              "zip",
              "manual"
            ]
          },
          "source_url": {
            "type": "string",
            "nullable": true
          },
          "pinned_commit_sha": {
            "type": "string",
            "nullable": true,
            "description": "Commit SHA the skill was imported from (GitHub imports)"
          },
          "applies_to": {
            "type": "array",
            "description": "Generation surfaces the skill applies to. Defaults to [\"text\"]. \"text\" covers articles, social, pages, and chat; \"image\" shapes the AI step that writes image prompts; \"video\" shapes the video script step.",
            "items": {
              "type": "string",
              "enum": [
                "text",
                "image",
                "video"
              ]
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "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
          }
        }
      },
      "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"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "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"
          }
        }
      },
      "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
          }
        }
      },
      "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"
              }
            }
          }
        }
      },
      "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
          }
        }
      },
      "SocialAdTotals": {
        "type": "object",
        "properties": {
          "spend": {
            "type": "number"
          },
          "impressions": {
            "type": "integer"
          },
          "clicks": {
            "type": "integer"
          },
          "conversions": {
            "type": "integer"
          },
          "reach": {
            "type": "integer"
          }
        }
      },
      "SocialAd": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "platform": {
            "type": "string",
            "nullable": true,
            "description": "Platform slug (facebook, instagram, google, tiktok, linkedin, pinterest, twitter)"
          },
          "status": {
            "type": "string",
            "nullable": true
          },
          "goal": {
            "type": "string",
            "nullable": true
          },
          "spend": {
            "type": "number"
          },
          "currency": {
            "type": "string"
          },
          "impressions": {
            "type": "integer"
          },
          "clicks": {
            "type": "integer"
          },
          "reach": {
            "type": "integer"
          },
          "ctr": {
            "type": "number"
          },
          "cpc": {
            "type": "number"
          },
          "cpm": {
            "type": "number"
          },
          "conversions": {
            "type": "integer"
          },
          "campaign_name": {
            "type": "string",
            "nullable": true
          },
          "ad_set_name": {
            "type": "string",
            "nullable": true
          },
          "is_external": {
            "type": "boolean",
            "description": "True when the ad was discovered from the ad platform (not created via Cuppa boost)"
          },
          "platform_ad_id": {
            "type": "string",
            "nullable": true
          },
          "platform_campaign_id": {
            "type": "string",
            "nullable": true
          },
          "platform_ad_account_id": {
            "type": "string",
            "nullable": true
          },
          "budget_amount": {
            "type": "number",
            "nullable": true
          },
          "budget_type": {
            "type": "string",
            "nullable": true
          },
          "ad_type": {
            "type": "string",
            "nullable": true
          },
          "last_synced_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "SocialAdCampaign": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "platform_campaign_id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "platform": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "nullable": true
          },
          "review_status": {
            "type": "string",
            "nullable": true
          },
          "platform_campaign_status": {
            "type": "string",
            "nullable": true
          },
          "ad_count": {
            "type": "integer",
            "nullable": true
          },
          "currency": {
            "type": "string"
          },
          "spend": {
            "type": "number"
          },
          "impressions": {
            "type": "integer"
          },
          "clicks": {
            "type": "integer"
          },
          "reach": {
            "type": "integer"
          },
          "ctr": {
            "type": "number"
          },
          "cpc": {
            "type": "number"
          },
          "cpm": {
            "type": "number"
          },
          "conversions": {
            "type": "integer"
          },
          "platform_ad_account_id": {
            "type": "string",
            "nullable": true
          },
          "platform_ad_account_name": {
            "type": "string",
            "nullable": true
          },
          "platform_objective": {
            "type": "string",
            "nullable": true
          },
          "optimization_goal": {
            "type": "string",
            "nullable": true
          },
          "budget_amount": {
            "type": "number",
            "nullable": true
          },
          "budget_type": {
            "type": "string",
            "nullable": true
          },
          "budget_level": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "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
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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
          }
        }
      },
      "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"
                }
              }
            }
          }
        }
      },
      "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"
              }
            }
          }
        }
      },
      "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
          }
        }
      },
      "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"
              }
            }
          }
        ]
      },
      "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
          }
        }
      },
      "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"
          }
        }
      },
      "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"
              }
            }
          }
        ]
      },
      "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"
                  }
                }
              }
            }
          },
          "searchBreakdown": {
            "type": "object",
            "description": "Per-engine split of the combined organic clicks/impressions (last 30 days). Bing values are 0 unless a Bing Webmaster property is connected.",
            "properties": {
              "google": {
                "type": "object",
                "properties": {
                  "clicks": {
                    "type": "integer"
                  },
                  "impressions": {
                    "type": "integer"
                  }
                }
              },
              "bing": {
                "type": "object",
                "properties": {
                  "clicks": {
                    "type": "integer"
                  },
                  "impressions": {
                    "type": "integer"
                  }
                }
              }
            }
          },
          "visibilityScore": {
            "type": "object",
            "nullable": true,
            "properties": {
              "score": {
                "type": "number"
              },
              "organicScore": {
                "type": "number"
              },
              "aiVisibilityScore": {
                "type": "number"
              },
              "contentQualityScore": {
                "type": "number"
              },
              "socialScore": {
                "type": "number"
              },
              "change": {
                "type": "number"
              },
              "lastCalculatedDate": {
                "type": "string",
                "format": "date",
                "nullable": true,
                "description": "Date the Brand Visibility Score was last calculated (YYYY-MM-DD)"
              }
            }
          },
          "quickWins": {
            "type": "object",
            "properties": {
              "pagesLosingTraffic": {
                "type": "integer"
              },
              "pagesNotCitedByAi": {
                "type": "integer"
              },
              "pagesAgingOut": {
                "type": "integer"
              },
              "strikingDistanceKeywords": {
                "type": "integer"
              }
            }
          }
        }
      },
      "PerformancePages": {
        "type": "object",
        "properties": {
          "pages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "pageUrl": {
                  "type": "string"
                },
                "pageTitle": {
                  "type": "string",
                  "nullable": true
                },
                "searchVisibility": {
                  "type": "string",
                  "enum": [
                    "in_search",
                    "sitemap_only"
                  ]
                },
                "searchVisibilityLabel": {
                  "type": "string"
                },
                "primaryKeyword": {
                  "type": "string",
                  "nullable": true
                },
                "contentGrade": {
                  "type": "number",
                  "nullable": true
                },
                "organicClicks": {
                  "type": "integer"
                },
                "organicImpressions": {
                  "type": "integer"
                },
                "avgPosition": {
                  "type": "number",
                  "nullable": true
                },
                "aiCitations": {
                  "type": "integer"
                },
                "aiPromptsCount": {
                  "type": "integer"
                },
                "socialEngagements": {
                  "type": "integer"
                },
                "isCuppaArticle": {
                  "type": "boolean"
                },
                "articleId": {
                  "type": "string",
                  "format": "uuid",
                  "nullable": true
                },
                "ga4Sessions": {
                  "type": "integer"
                }
              }
            }
          },
          "total": {
            "type": "integer"
          },
          "page": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "searchVisibilityCounts": {
            "type": "object",
            "properties": {
              "inSearch": {
                "type": "integer"
              },
              "sitemapOnly": {
                "type": "integer"
              }
            }
          }
        }
      },
      "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"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "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"
                }
              }
            }
          }
        }
      },
      "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
                }
              }
            }
          }
        }
      },
      "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
          }
        }
      },
      "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"
              }
            }
          }
        ]
      }
    },
    "/v1/performance/overview": {
      "get": {
        "summary": "Get brand performance overview",
        "description": "Returns KPIs (organic clicks, impressions, CTR, AI citations, social reach, sessions, content grade), Brand Visibility Score breakdown, and Quick Wins.",
        "tags": [
          "Performance"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Performance overview",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PerformanceOverview"
                }
              }
            }
          }
        }
      }
    },
    "/v1/performance/website-audit": {
      "get": {
        "summary": "Get latest website audit",
        "description": "Returns the latest Website Audit for a site: overall technical health\nscore (0-100 vs. the web standards spec), score delta since the previous\nrun, category breakdown (Foundations, SEO, Security, Agent Readiness,\nPerformance, Resilience), pass/fail/warn/skip counts, and the number of\nopen opportunities. This audit score contributes 10% of the Brand\nVisibility Score. Returns `summary: null` if no audit has run yet.\n",
        "tags": [
          "Performance"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Latest website audit summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary": {
                      "nullable": true,
                      "type": "object",
                      "properties": {
                        "auditId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "running",
                            "complete",
                            "failed"
                          ]
                        },
                        "domain": {
                          "type": "string"
                        },
                        "overallScore": {
                          "type": "number"
                        },
                        "categoryScores": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "number"
                          }
                        },
                        "checksPassed": {
                          "type": "integer"
                        },
                        "checksFailed": {
                          "type": "integer"
                        },
                        "checksWarned": {
                          "type": "integer"
                        },
                        "checksSkipped": {
                          "type": "integer"
                        },
                        "scoreDelta": {
                          "type": "number",
                          "nullable": true
                        },
                        "errorReason": {
                          "type": "string",
                          "nullable": true
                        },
                        "completedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "openOpportunities": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Run a website audit",
        "description": "Enqueues a fresh Website Audit for the site. Rate limited to one run per\nhour per site. Returns immediately; poll the GET endpoint for results\n(usually ready within a minute).\n",
        "tags": [
          "Performance"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Audit queued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "queued": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "An audit is already running"
          },
          "429": {
            "description": "Rate limited (one run per hour per site)"
          }
        }
      }
    },
    "/v1/performance/website-audit/history": {
      "get": {
        "summary": "Get website audit score history",
        "description": "Returns completed website audit scores over time (oldest first).",
        "tags": [
          "Performance"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 30,
              "maximum": 90
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Audit score history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "history": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "date": {
                            "type": "string"
                          },
                          "score": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/performance/website-audit/checks": {
      "get": {
        "summary": "Get website audit check results",
        "description": "Returns the per-check results for an audit run. Defaults to the latest\ncompleted run; pass `audit_id` to fetch a specific run.\n",
        "tags": [
          "Performance"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "audit_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Check results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "auditId": {
                      "type": "string",
                      "format": "uuid",
                      "nullable": true
                    },
                    "checks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "checkId": {
                            "type": "string"
                          },
                          "category": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pass",
                              "fail",
                              "warn",
                              "skip",
                              "error"
                            ]
                          },
                          "specStatus": {
                            "type": "string"
                          },
                          "severity": {
                            "type": "string"
                          },
                          "message": {
                            "type": "string",
                            "nullable": true
                          },
                          "evidence": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/performance/website-audit/opportunities": {
      "get": {
        "summary": "Get open website audit opportunities",
        "description": "Returns open, agent-actionable opportunities from the latest audit, each\nwith a priority, fix hint, spec reference, and a ready-to-run agent prompt.\n",
        "tags": [
          "Performance"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Open opportunities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "opportunities": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "checkId": {
                            "type": "string"
                          },
                          "category": {
                            "type": "string"
                          },
                          "priority": {
                            "type": "string",
                            "enum": [
                              "critical",
                              "high",
                              "medium",
                              "low"
                            ]
                          },
                          "title": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string",
                            "nullable": true
                          },
                          "fixHint": {
                            "type": "string",
                            "nullable": true
                          },
                          "agentPrompt": {
                            "type": "string",
                            "nullable": true
                          },
                          "specUrl": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string"
                          },
                          "createdAt": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a website audit opportunity",
        "description": "Mark an opportunity as resolved, dismissed, in_progress, or open.",
        "tags": [
          "Performance"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "opportunity_id",
                  "status"
                ],
                "properties": {
                  "opportunity_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "open",
                      "in_progress",
                      "resolved",
                      "dismissed"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/performance/bing": {
      "get": {
        "summary": "Get Bing Webmaster Tools performance",
        "description": "Returns Bing Webmaster Tools search performance for a site: total clicks,\nimpressions, average position, CTR, top queries and top pages.\nUse alongside `/v1/performance/overview` (whose organic KPIs are the\ncombined Google + Bing totals, with a `searchBreakdown` per engine) to\ncompare engines and find queries or pages that win on one but not the other.\nReturns `connected: false` when no Bing property is linked to the site.\n",
        "tags": [
          "Performance"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bing performance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connected": {
                      "type": "boolean"
                    },
                    "hasData": {
                      "type": "boolean"
                    },
                    "totals": {
                      "type": "object",
                      "properties": {
                        "clicks": {
                          "type": "integer"
                        },
                        "impressions": {
                          "type": "integer"
                        },
                        "ctr": {
                          "type": "number"
                        },
                        "avgPosition": {
                          "type": "number"
                        },
                        "queryCount": {
                          "type": "integer"
                        }
                      }
                    },
                    "topQueries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "query": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          },
                          "impressions": {
                            "type": "integer"
                          },
                          "position": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "topPages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "url": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          },
                          "impressions": {
                            "type": "integer"
                          },
                          "position": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/tracker/rankings": {
      "get": {
        "summary": "Get DataForSEO domain keyword rankings",
        "description": "Returns the latest DataForSEO keyword rankings snapshot for a site:\nevery keyword the domain ranks for with its current position, the prior\nsnapshot's position, the rank delta (positive = moved up the SERP), the\nranking URL and monthly search volume.\n\nSnapshots are taken weekly. Pass `date` (YYYY-MM-DD) to fetch a specific\nhistorical snapshot instead of the latest. Requires the\n`dataforseo_tracker` feature flag (PBN); other teams receive 403.\n",
        "tags": [
          "Tracker"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "date",
            "in": "query",
            "description": "Snapshot date (YYYY-MM-DD). Defaults to the latest snapshot.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 200,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Domain keyword rankings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "siteId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "snapshotDate": {
                      "type": "string",
                      "format": "date",
                      "nullable": true
                    },
                    "count": {
                      "type": "integer"
                    },
                    "rankings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "keyword": {
                            "type": "string"
                          },
                          "position": {
                            "type": "integer",
                            "nullable": true
                          },
                          "previousPosition": {
                            "type": "integer",
                            "nullable": true
                          },
                          "delta": {
                            "type": "integer",
                            "nullable": true,
                            "description": "previousPosition - position (positive = improved)"
                          },
                          "url": {
                            "type": "string",
                            "nullable": true
                          },
                          "searchVolume": {
                            "type": "integer",
                            "nullable": true
                          },
                          "locationCode": {
                            "type": "integer"
                          },
                          "snapshotDate": {
                            "type": "string",
                            "format": "date"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "dataforseo_tracker feature flag not enabled for this team"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/tracker/indexation": {
      "get": {
        "summary": "Get DataForSEO real per-URL indexation",
        "description": "Returns real Google indexation status per article for a site, measured\nvia DataForSEO `site:<url>` SERP queries (vs Ahrefs' top-10 inference).\nEach item is `indexed`, `not_indexed`, `pending`, or `null` (never\nscanned). `indexationRate` is the share of *checked* articles that are\nindexed (pending/unchecked excluded from the denominator).\n\nRequires the `dataforseo_tracker` feature flag (PBN); other teams\nreceive 403.\n",
        "tags": [
          "Tracker"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 500,
              "maximum": 2000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Per-URL real indexation status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "siteId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "totals": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer",
                          "description": "All complete, non-draft articles for the site (site-wide, not this page)"
                        },
                        "indexed": {
                          "type": "integer"
                        },
                        "notIndexed": {
                          "type": "integer"
                        },
                        "pending": {
                          "type": "integer"
                        },
                        "noUrl": {
                          "type": "integer",
                          "description": "Complete articles with no checkable URL (evaluated, not backlog)"
                        },
                        "unchecked": {
                          "type": "integer"
                        },
                        "indexationRate": {
                          "type": "number",
                          "description": "indexed / (indexed + not_indexed) as a percentage"
                        }
                      }
                    },
                    "count": {
                      "type": "integer"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "articleId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "title": {
                            "type": "string",
                            "nullable": true
                          },
                          "url": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "indexed",
                              "not_indexed",
                              "pending"
                            ]
                          },
                          "checkedAt": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "dataforseo_tracker feature flag not enabled for this team"
          },
          "404": {
            "description": "Site not found"
          }
        }
      }
    },
    "/v1/performance/pages": {
      "get": {
        "summary": "List performance pages with search visibility",
        "description": "Returns paginated site pages with organic metrics and search visibility labels.\n`in_search` means the URL has Google Search Console search analytics data.\n`sitemap_only` means the URL is on the link-engine sitemap index but has no GSC data yet (not confirmed non-indexed).\n",
        "tags": [
          "Performance"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 25,
              "maximum": 100
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "clicks_desc",
                "impressions_desc",
                "position_asc",
                "ai_citations_desc",
                "grade_asc",
                "age_desc",
                "sessions_desc",
                "engagements_desc",
                "social_desc",
                "ctr_desc"
              ],
              "default": "clicks_desc"
            }
          },
          {
            "name": "search_visibility",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "in_search",
                "sitemap_only"
              ]
            }
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "position_range",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "page1_top",
                "page1",
                "almost_page1",
                "page2_plus"
              ]
            }
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "cuppa",
                "external",
                "subdomain",
                "all"
              ],
              "default": "all"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Performance pages",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PerformancePages"
                }
              }
            }
          }
        }
      }
    },
    "/v1/performance/content-health": {
      "get": {
        "summary": "Get content health analysis",
        "description": "Returns top pages by clicks, content decay (pages losing traffic), striking distance keywords, and keyword cannibalization.",
        "tags": [
          "Performance"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Content health data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentHealth"
                }
              }
            }
          }
        }
      }
    },
    "/v1/performance/ai-visibility": {
      "get": {
        "summary": "Get AI visibility data",
        "description": "Returns LLM mentions (ChatGPT, Google AI Overview), top prompts, top cited pages, and citation gaps vs competitors.",
        "tags": [
          "Performance"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 30,
              "maximum": 365
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 25,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "AI visibility data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiVisibility"
                }
              }
            }
          }
        }
      }
    },
    "/v1/performance/backlinks": {
      "get": {
        "summary": "Get backlink profile",
        "description": "Returns domain rating, backlink counts, and top referring domains. Requires Ahrefs connection.",
        "tags": [
          "Performance"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Backlink data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Backlinks"
                }
              }
            }
          }
        }
      }
    },
    "/v1/newsletters": {
      "get": {
        "summary": "List newsletters",
        "description": "List generated newsletters for a site.",
        "tags": [
          "Newsletters"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "scheduled",
                "ready",
                "sent"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Newsletter list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "newsletters": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Newsletter"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/newsletters/{id}": {
      "get": {
        "summary": "Get newsletter detail",
        "description": "Get full newsletter including content, HTML, and metadata.",
        "tags": [
          "Newsletters"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Newsletter detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NewsletterDetail"
                }
              }
            }
          }
        }
      }
    },
    "/v1/newsletters/generate": {
      "post": {
        "summary": "Generate newsletter",
        "description": "Generate a weekly newsletter roundup from published articles. Uses brand context for tone.",
        "tags": [
          "Newsletters"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "week_start": {
                    "type": "string",
                    "format": "date",
                    "description": "Monday of the target week (YYYY-MM-DD). Defaults to current week."
                  },
                  "model": {
                    "type": "string",
                    "description": "AI model for generation (default gpt-5)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Newsletter generated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "subject": {
                      "type": "string"
                    },
                    "articleCount": {
                      "type": "integer"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}