{
  "openapi": "3.1.0",
  "info": {
    "title": "Frase API",
    "version": "1.0.0",
    "description": "The Frase API provides programmatic access to your SEO content platform. Use it to manage content, research, audits, AI visibility tracking, and more.\n\n## Authentication\n\nAll API requests require authentication using an API key. Include your key in the `X-API-KEY` header:\n\n```\nX-API-KEY: sk_live_your_api_key_here\n```\n\nFor legacy compatibility, the `token` header is also supported.\n\n## Rate Limits\n\nThree independent limits apply, each with its own headers and error code. Headers are returned on `429` responses, not on successful ones.\n\n**Per-minute burst** - 60/min on trial and Starter, 120 Professional, 300 Scale, 1,000 Enterprise. Error code `rate_limit_exceeded`.\n- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (epoch seconds)\n\n**Sustained hourly ceiling** - 2,000/hour trial, 3,000 Starter, 5,000 Professional, 15,000 Scale, 50,000 Enterprise. Error code `hourly_limit_exceeded`.\n- `X-RateLimit-Hourly-Limit`, `X-RateLimit-Hourly-Remaining`, `X-RateLimit-Hourly-Reset` (epoch seconds)\n\n**Monthly request budget** - error code `monthly_budget_exceeded`, headers `X-Monthly-Limit`, `X-Monthly-Used`, `X-Monthly-Remaining`.\n\nEvery `429` carries `Retry-After` in seconds. On the hourly ceiling this can be up to 3,600, so clients should honour it rather than retrying on a short fixed backoff - a retry sooner than `Retry-After` cannot succeed.\n\n## Errors\n\nThe API uses standard HTTP status codes and returns errors in a consistent format:\n\n```json\n{\n  \"error\": {\n    \"type\": \"authentication_error\",\n    \"code\": \"invalid_api_key\",\n    \"message\": \"Invalid API key provided.\",\n    \"doc_url\": \"https://docs.frase.io/api/errors#invalid_api_key\"\n  }\n}\n```\n\n## Changelog\n\nBreaking changes are listed here, newest first. \"Breaking\" means a field that was always present with a value can now be `null`, or an existing value now means something different — not that a field was removed or renamed. Additive fields are not listed.\n\n### 2026-08-31 — Fact `sources[]` may omit `url`, and minted facts default to `approved`\n\n- `GET /briefs/{id}/facts`, `PATCH /briefs/{id}/facts/{factId}` → a `sources[]` entry may now carry only `title`, with no `url` or `domain`. Research names a publisher far more often than it captures a link (793 of 801 plan-evidence items in production), and those names were previously discarded rather than returned. Read `url` defensively.\n- `GET /briefs/{id}/facts` → `approval` on a newly minted fact is now `approved` rather than `pending`. A client polling for `pending` facts to review will see far fewer; rejection is unchanged and remains permanent. Facts the writer asserted in its own output (`provenance: generated`) are still minted `pending`.\n\n### 2026-08-24 — Content Guard's hasPublishedUrl is now recoverability, not the stored URL\n\n- `GET /content/{id}/monitoring` → `hasPublishedUrl`: was a judgment on the STORED URL (false for a relative path even when the page was live). It now answers \"could Guard watch this article right now\" — the stored URL when absolute, or an address the server recovers (CMS inventory; FraseCMS re-derivation from current settings when a live published post exists). `true` no longer implies the stored URL itself is absolute, and a FraseCMS article published before domain setup flips to `true` when setup finishes, with no re-publish. It remains exactly the condition enabling enforces.\n- `publishedUrlIssue` is now the RESIDUAL after recovery failed, not a raw-column classification — \"not_absolute\" can also mean the FraseCMS post is not live or FraseCMS is disabled for the site.\n- `POST /content/{id}/publish` → `url` (frase_cms): now derived from the site's current CMS settings rather than the adapter's host-of-the-moment value; the same URL is stored on the content row and sent in the content.published webhook.\n\n### 2026-08-10 — Single-page audit content classification is canonical\n\n- `POST /audits/page` → `content_type`: now returns one of the canonical 18 content types, or `null` when classification is not applicable or unmeasured. It previously returned the retired audit detector's broader type vocabulary.\n- `POST /audits/page` → `content_type_confidence`: now returns `high`, `medium`, `low`, or `null`; it previously returned a numeric confidence.\n- Login and error pages now return `content_type_status: not_applicable` and null page-score families rather than publishing scores for non-content responses. Add null guards before doing arithmetic on score fields.\n\n### 2026-08-09 — Content Guard's published-URL check is stricter\n\n- `GET /content/{id}/monitoring` → `hasPublishedUrl`: was a presence test on the stored published URL, so a stored RELATIVE path (`/blog/post`, which a FraseCMS publish produces before domain setup) reported `true` while `POST` to the same path refused to enable on it. It is now the same judgment enabling enforces: `false` unless the stored URL is an absolute http(s) address. The read and the write can no longer disagree, so `hasPublishedUrl: false` reliably means the enable would be rejected.\n\nAlso in this release, additive: `publishedUrlIssue` on the same response names WHICH case a `false` is — `missing` (never published anywhere) or `not_absolute` (published, but to a path). Use it rather than re-deriving the reason from the URL, because the two have different remedies: publish it, versus finish domain setup. Both operations on `/content/{id}/monitoring` are newly documented in this spec; apart from the field above their behaviour is unchanged.\n\n### 2026-08-07 — an unmeasured score reports as unmeasured\n\nThree fields stopped reporting a fabricated number where nothing had been measured. If your integration does arithmetic on them, add a null guard.\n\n- `GET /site-health` → `average_scores.technical`: was always an integer and returned `0` when no page had a readable technical measurement, so a never-audited site was indistinguishable from a site scoring 0. Now `null` in exactly those cases. `content` and `aeo` are unchanged.\n- `GET /site-health` → `pages[].technical_score`: on an audited page this was always an integer, computed as 100 minus 10 per issue the display taxonomy called technical. A page whose HTML we could not read scored a confident number. Now `null` when no technical check could run. (It was already `null` on a never-audited page.)\n- `GET /cms/posts/{id}/performance` → `health_status`: a post with an audit row but no computable overall score was graded as if it scored 100, so it came back `\"healthy\"`. It now comes back `\"no_data\"`. The set of possible values is unchanged and `\"no_data\"` was already reachable; what changed is which posts land in it.\n\nAlso in this release, additive: `pages[].technical_score`, `click_depth`, `is_orphan` and `is_dead_end` on `GET /audits/{id}`; `authority_summary.links_measured` and `authority_summary.depth_measured` on `GET /site-health`; `links_measured` and `depth_measured` on `GET /site-health/links` in its `site_id` mode. Two flags rather than one because the link graph carries two independent measurements: orphan-ness and dead-ends come from the extracted edges and need no site root, while click depth needs one, so a manually scoped audit reports `links_measured: true` alongside `depth_measured: false`. Each is documented on its own field.",
    "contact": {
      "name": "Frase Support",
      "url": "https://frase.io",
      "email": "support@frase.io"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.frase.io/company/terms"
    }
  },
  "servers": [
    {
      "url": "https://next.frase.io/api/v1",
      "description": "Production"
    },
    {
      "url": "/api/v1",
      "description": "This host"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Answers",
      "description": "Frase Answers: ask the site's knowledge base a question (SSE streaming)"
    },
    {
      "name": "Atomizations",
      "description": "Repurpose an article into channel-native assets (LinkedIn carousel, X thread, newsletter, Instagram carousel)"
    },
    {
      "name": "Audit",
      "description": "Client telemetry ingest (MCP tool invocations) - distinct from Audits (site audits)"
    },
    {
      "name": "Content",
      "description": "Manage generated content articles"
    },
    {
      "name": "Briefs",
      "description": "Content briefs and outlines"
    },
    {
      "name": "Research",
      "description": "AI-powered research"
    },
    {
      "name": "Audits",
      "description": "Site audits and SEO analysis"
    },
    {
      "name": "Site Health",
      "description": "Per-site health rollups derived from the latest audit"
    },
    {
      "name": "Sites",
      "description": "Manage websites"
    },
    {
      "name": "AI Visibility",
      "description": "Track brand visibility across AI platforms"
    },
    {
      "name": "Analytics",
      "description": "Google Search Console and performance data"
    },
    {
      "name": "SERP",
      "description": "SERP analysis and competitor research"
    },
    {
      "name": "Optimizations",
      "description": "Content optimization suggestions"
    },
    {
      "name": "Webhooks",
      "description": "Webhook subscriptions for event notifications"
    },
    {
      "name": "Jobs",
      "description": "Async job status tracking"
    },
    {
      "name": "Competitive Analysis",
      "description": "Competitive page analysis and gap identification"
    },
    {
      "name": "Legacy",
      "description": "Legacy API endpoints for backward compatibility"
    },
    {
      "name": "Rules",
      "description": "Content rules for automated quality checks"
    },
    {
      "name": "Clusters",
      "description": "Topic clusters that organize content and briefs by theme"
    },
    {
      "name": "Playbooks",
      "description": "Content playbooks for structured content workflows"
    },
    {
      "name": "Brand",
      "description": "Brand governance bundle and terminology checks for on-brand authoring"
    },
    {
      "name": "Rule Sets",
      "description": "Manage content rule sets for automated content evaluation"
    },
    {
      "name": "Templates",
      "description": "Content templates for standardized outlines and formatting"
    },
    {
      "name": "CMS",
      "description": "Frase CMS post management and bulk import"
    },
    {
      "name": "Comments",
      "description": "List, resolve, and request AI comments on content articles"
    },
    {
      "name": "Opportunities",
      "description": "Unified opportunity list across all discovery sources"
    }
  ],
  "paths": {
    "/next-actions": {
      "get": {
        "operationId": "getNextActions",
        "summary": "What to do now on a site",
        "description": "The ranked, cross-domain list of what to do now on one site: the same daily brief the workspace's Home page shows, as stored, with nothing ranked at request time. `todos` are the actions, `updates` the news, `more_todos` the next-best actions behind the day's cap; every item carries a deterministic `cta` and, where a v1 row backs it, a `resource` pointer naming what to open next. `status` is `ready` when a brief is stored for the site, or when the day's run finished without finding anything for it (empty lists, the run's date), and `none` when the brief has not reached the site yet (empty lists, `brief_date` null). The newest ready brief dated no later than the current UTC day is served; API keys have no viewer clock. A member-bound MCP token is served by the member's reveal hour on the UTC clock, as Home serves a member whose browser clock it has not seen. Kinds with no v1 route behind them today (comments, the review queue, Answers signals, page updates, setup nudges) are not carried, nor is crawlability, which the brief ranks for the organization and never stores on a site's row; they arrive under a dated note here when their routes exist. Requires the read scope of every area the brief spans or points at: `read:opportunities`, `read:analytics`, `read:audits`, `read:content`, `read:ai-visibility`, `read:site-health`. Reads are org-scoped, so a site belonging to another organization, or one in Trash, returns 404.",
        "tags": [
          "Next actions"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The site's next actions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "site_id",
                        "brief_date",
                        "status",
                        "todos",
                        "updates",
                        "more_todos",
                        "home_only_items"
                      ],
                      "properties": {
                        "site_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "brief_date": {
                          "type": "string",
                          "format": "date",
                          "nullable": true,
                          "description": "The day the brief is for."
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "none"
                          ]
                        },
                        "home_only_items": {
                          "type": "integer",
                          "description": "Items in the brief that only Home shows: team work the API carries no resource for (comments, review queue, citation fixes, answers signals, setup nudges, crawlability), counted as stored. Home re-checks setup nudges at read time and hides a satisfied one, so the count is an upper bound. An empty list here is not by itself a quiet day."
                        },
                        "todos": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "id",
                              "kind",
                              "domain",
                              "title",
                              "context",
                              "severity",
                              "score",
                              "cta",
                              "resource",
                              "site_id",
                              "carried_over",
                              "more",
                              "completed_at"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The brief's stable item id. Completions are keyed on it."
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "performance_alert",
                                  "analytics_insight",
                                  "audit",
                                  "opportunity",
                                  "optimization_win",
                                  "ai_visibility"
                                ]
                              },
                              "domain": {
                                "type": "string",
                                "enum": [
                                  "analytics",
                                  "site_health",
                                  "opportunities",
                                  "optimizations",
                                  "ai_visibility"
                                ]
                              },
                              "title": {
                                "type": "string"
                              },
                              "context": {
                                "type": "string",
                                "description": "One or two sentences on why it matters today."
                              },
                              "severity": {
                                "type": "string",
                                "enum": [
                                  "critical",
                                  "high",
                                  "medium",
                                  "low"
                                ]
                              },
                              "score": {
                                "type": "number",
                                "nullable": true
                              },
                              "cta": {
                                "type": "object",
                                "required": [
                                  "label",
                                  "path"
                                ],
                                "description": "Stamped at ranking, never narrated.",
                                "properties": {
                                  "label": {
                                    "type": "string"
                                  },
                                  "path": {
                                    "type": "string",
                                    "description": "App-relative path the action opens."
                                  }
                                }
                              },
                              "resource": {
                                "type": "object",
                                "nullable": true,
                                "required": [
                                  "type",
                                  "id"
                                ],
                                "description": "What to open next: `opportunity` reads GET /opportunities/{id}, `content` GET /content/{id}, `audit` GET /audits/{id}, `audit_run` asks for a new audit of the site whose id it carries (POST /audits), `ai_visibility_prompt` GET /ai-visibility/prompts/{id}. Null when the action lands on a page rather than a row.",
                                "properties": {
                                  "type": {
                                    "type": "string",
                                    "enum": [
                                      "opportunity",
                                      "content",
                                      "audit",
                                      "audit_run",
                                      "ai_visibility_prompt"
                                    ]
                                  },
                                  "id": {
                                    "type": "string"
                                  }
                                }
                              },
                              "site_id": {
                                "type": "string",
                                "format": "uuid",
                                "nullable": true
                              },
                              "carried_over": {
                                "type": "boolean",
                                "description": "True when the item also stood in the previous day's brief and was not completed."
                              },
                              "more": {
                                "type": "object",
                                "nullable": true,
                                "required": [
                                  "count",
                                  "note",
                                  "path"
                                ],
                                "properties": {
                                  "count": {
                                    "type": "integer"
                                  },
                                  "note": {
                                    "type": "string"
                                  },
                                  "path": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "The app path that opens the full list behind the tail, where the item's cta opens one row."
                                  }
                                }
                              },
                              "completed_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              }
                            }
                          }
                        },
                        "updates": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "id",
                              "kind",
                              "domain",
                              "title",
                              "context",
                              "severity",
                              "score",
                              "cta",
                              "resource",
                              "site_id",
                              "carried_over",
                              "more",
                              "completed_at"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The brief's stable item id. Completions are keyed on it."
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "performance_alert",
                                  "analytics_insight",
                                  "audit",
                                  "opportunity",
                                  "optimization_win",
                                  "ai_visibility"
                                ]
                              },
                              "domain": {
                                "type": "string",
                                "enum": [
                                  "analytics",
                                  "site_health",
                                  "opportunities",
                                  "optimizations",
                                  "ai_visibility"
                                ]
                              },
                              "title": {
                                "type": "string"
                              },
                              "context": {
                                "type": "string",
                                "description": "One or two sentences on why it matters today."
                              },
                              "severity": {
                                "type": "string",
                                "enum": [
                                  "critical",
                                  "high",
                                  "medium",
                                  "low"
                                ]
                              },
                              "score": {
                                "type": "number",
                                "nullable": true
                              },
                              "cta": {
                                "type": "object",
                                "required": [
                                  "label",
                                  "path"
                                ],
                                "description": "Stamped at ranking, never narrated.",
                                "properties": {
                                  "label": {
                                    "type": "string"
                                  },
                                  "path": {
                                    "type": "string",
                                    "description": "App-relative path the action opens."
                                  }
                                }
                              },
                              "resource": {
                                "type": "object",
                                "nullable": true,
                                "required": [
                                  "type",
                                  "id"
                                ],
                                "description": "What to open next: `opportunity` reads GET /opportunities/{id}, `content` GET /content/{id}, `audit` GET /audits/{id}, `audit_run` asks for a new audit of the site whose id it carries (POST /audits), `ai_visibility_prompt` GET /ai-visibility/prompts/{id}. Null when the action lands on a page rather than a row.",
                                "properties": {
                                  "type": {
                                    "type": "string",
                                    "enum": [
                                      "opportunity",
                                      "content",
                                      "audit",
                                      "audit_run",
                                      "ai_visibility_prompt"
                                    ]
                                  },
                                  "id": {
                                    "type": "string"
                                  }
                                }
                              },
                              "site_id": {
                                "type": "string",
                                "format": "uuid",
                                "nullable": true
                              },
                              "carried_over": {
                                "type": "boolean",
                                "description": "True when the item also stood in the previous day's brief and was not completed."
                              },
                              "more": {
                                "type": "object",
                                "nullable": true,
                                "required": [
                                  "count",
                                  "note",
                                  "path"
                                ],
                                "properties": {
                                  "count": {
                                    "type": "integer"
                                  },
                                  "note": {
                                    "type": "string"
                                  },
                                  "path": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "The app path that opens the full list behind the tail, where the item's cta opens one row."
                                  }
                                }
                              },
                              "completed_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              }
                            }
                          }
                        },
                        "more_todos": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "id",
                              "kind",
                              "domain",
                              "title",
                              "context",
                              "severity",
                              "score",
                              "cta",
                              "resource",
                              "site_id",
                              "carried_over",
                              "more",
                              "completed_at"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The brief's stable item id. Completions are keyed on it."
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "performance_alert",
                                  "analytics_insight",
                                  "audit",
                                  "opportunity",
                                  "optimization_win",
                                  "ai_visibility"
                                ]
                              },
                              "domain": {
                                "type": "string",
                                "enum": [
                                  "analytics",
                                  "site_health",
                                  "opportunities",
                                  "optimizations",
                                  "ai_visibility"
                                ]
                              },
                              "title": {
                                "type": "string"
                              },
                              "context": {
                                "type": "string",
                                "description": "One or two sentences on why it matters today."
                              },
                              "severity": {
                                "type": "string",
                                "enum": [
                                  "critical",
                                  "high",
                                  "medium",
                                  "low"
                                ]
                              },
                              "score": {
                                "type": "number",
                                "nullable": true
                              },
                              "cta": {
                                "type": "object",
                                "required": [
                                  "label",
                                  "path"
                                ],
                                "description": "Stamped at ranking, never narrated.",
                                "properties": {
                                  "label": {
                                    "type": "string"
                                  },
                                  "path": {
                                    "type": "string",
                                    "description": "App-relative path the action opens."
                                  }
                                }
                              },
                              "resource": {
                                "type": "object",
                                "nullable": true,
                                "required": [
                                  "type",
                                  "id"
                                ],
                                "description": "What to open next: `opportunity` reads GET /opportunities/{id}, `content` GET /content/{id}, `audit` GET /audits/{id}, `audit_run` asks for a new audit of the site whose id it carries (POST /audits), `ai_visibility_prompt` GET /ai-visibility/prompts/{id}. Null when the action lands on a page rather than a row.",
                                "properties": {
                                  "type": {
                                    "type": "string",
                                    "enum": [
                                      "opportunity",
                                      "content",
                                      "audit",
                                      "audit_run",
                                      "ai_visibility_prompt"
                                    ]
                                  },
                                  "id": {
                                    "type": "string"
                                  }
                                }
                              },
                              "site_id": {
                                "type": "string",
                                "format": "uuid",
                                "nullable": true
                              },
                              "carried_over": {
                                "type": "boolean",
                                "description": "True when the item also stood in the previous day's brief and was not completed."
                              },
                              "more": {
                                "type": "object",
                                "nullable": true,
                                "required": [
                                  "count",
                                  "note",
                                  "path"
                                ],
                                "properties": {
                                  "count": {
                                    "type": "integer"
                                  },
                                  "note": {
                                    "type": "string"
                                  },
                                  "path": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "The app path that opens the full list behind the tail, where the item's cta opens one row."
                                  }
                                }
                              },
                              "completed_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "site_id missing or not a UUID (`param: \"site_id\"`)"
          },
          "403": {
            "description": "The key lacks the read scope of an area the brief spans; the message names the missing scopes"
          },
          "404": {
            "description": "Site not found in this organization, or in Trash"
          }
        }
      }
    },
    "/atomizations": {
      "get": {
        "operationId": "listAtomizations",
        "summary": "List atomizations",
        "description": "Lists the calling organization's atomizations, most recently updated first. Requires the `read:atomize` scope. Results are page-based: `page` defaults to 1 and `page_size` defaults to 20 and is clamped to 100. `content_id` is validated as a UUID and returns 400 `invalid_param` otherwise. `type` and `status` are passed straight to the query without validation — a value outside the enums fails at the database and surfaces as a 500 `Failed to list atomizations`, so send only the documented values. Each item carries only summary columns; call `GET /atomizations/{id}` for the generated `data` and `assets`.",
        "tags": [
          "Atomizations"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "1-based page number. Values below 1 (and unparseable values) fall back to 1.",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "description": "Items per page; defaults to 20, ceiling 100. Negative values clamp to 1; 0 and unparseable values fall back to 20.",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "content_id",
            "in": "query",
            "description": "Only return atomizations derived from this content item. Must be a UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Filter by atomization type.",
            "schema": {
              "type": "string",
              "enum": [
                "linkedin_carousel",
                "twitter_thread",
                "newsletter",
                "instagram_carousel"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by status.",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "generating",
                "review",
                "published",
                "archived"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of atomizations",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Correlation id for this request"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "content_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "linkedin_carousel",
                              "twitter_thread",
                              "newsletter",
                              "instagram_carousel"
                            ]
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "draft",
                              "generating",
                              "review",
                              "published",
                              "archived"
                            ]
                          },
                          "published_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true,
                            "description": "ISO 8601 timestamp, or null when never published"
                          },
                          "published_url": {
                            "type": "string",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updated_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "description": "Note the camelCase keys — this endpoint emits the pagination bag verbatim.",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "pageSize": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "hasMore": {
                          "type": "boolean",
                          "description": "True when offset + returned items is still below total"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The API key lacks the `read:atomize` scope (`insufficient_scope`), the caller's IP is not allow-listed (`ip_not_allowed`), or the organization's subscription/trial is no longer active.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The listing query failed (this is also what an out-of-enum `type`/`status` produces).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "error": "Failed to list atomizations"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createAtomization",
        "summary": "Create (or regenerate) an atomization",
        "description": "Turns a published article into one channel-native asset. Requires the `write:atomize` scope.\n\nThe handler runs its checks in this order: body validation first (so a malformed request always gets its 400 rather than a 403/429), then the plan gate (Omni-Channel Atomization requires the `professional` plan or higher), then two rate limiters (20/hour per organization+user, 50/hour per organization), then billing.\n\nBilling charges one content credit per (organization, content, billing period), so a second type for the same article inside the same period is free by the ledger's unique claim, and a new period charges again. If the charge crosses the organization into paid per-article overage the response body sets `overage_incurred` to true and the `X-Frase-Overage-Incurred: true` header is added.\n\nGeneration is asynchronous: the row is created (or an existing row for the same content+type is reset) to `generating`, an `atomization/create` background event is dispatched, and 201 is returned immediately. Poll `GET /atomizations/{id}` for the finished payload. If a row for that content+type is already `generating`, the existing row is returned as-is with 201 — no charge, no second dispatch, and `overage_incurred` is false.\n\nIf the background dispatch itself fails, the row is released back to `draft` so the (already charged) caller can retry; the retry is free within the same period.",
        "tags": [
          "Atomizations"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "content_id",
                  "type"
                ],
                "properties": {
                  "content_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The content item to atomize. Must be a UUID belonging to your organization."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "linkedin_carousel",
                      "twitter_thread",
                      "newsletter",
                      "instagram_carousel"
                    ],
                    "description": "Required. The channel format to produce. The route only checks that this is a string; the enum is enforced one layer down and an unknown value comes back as a 400 with `param: \"input\"`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Atomization queued (or an already in-flight one returned unchanged)",
            "headers": {
              "X-Frase-Overage-Incurred": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                },
                "description": "Present only when this call crossed the organization into paid per-article overage"
              },
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Correlation id for this request"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "content_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "linkedin_carousel",
                            "twitter_thread",
                            "newsletter",
                            "instagram_carousel"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "generating"
                          ],
                          "description": "Always `generating` on this path — generation runs in the background."
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Creation time of the row. For a regenerated or already in-flight row this is the ORIGINAL creation time, not the time of this call."
                        },
                        "overage_incurred": {
                          "type": "boolean",
                          "description": "True when this call crossed the organization into paid per-article overage. Always false on the already-in-flight path, which does not charge."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`plan_upgrade_required` — the organization's plan does not include Omni-Channel Atomization (professional or higher); `subscription_inactive` — the subscription is canceled, paused, past due beyond grace, or the trial has expired; or an auth-layer refusal (`insufficient_scope` when the key lacks `write:atomize`, `ip_not_allowed`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "The content does not exist or belongs to another organization. Note this path returns the plain `{ \"data\": { \"error\": ... } }` envelope, not the structured error object.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "error": "Content not found or does not belong to this organization"
                  }
                }
              }
            }
          },
          "429": {
            "description": "One of three refusals, told apart by `error.code`: `rate_limit_exceeded` (20/hour per organization+user or 50/hour per organization — carries `Retry-After` plus the `X-RateLimit-*` bag), `article_limit_exceeded` (the organization's monthly content allowance is used up — `Retry-After` only when the reset instant is known), or `site_article_budget_exceeded` (a per-site article budget is exhausted; no organization-level overage or upgrade lifts it, only a site admin raising the budget). The API-key tier limiter and monthly budget in the auth layer can also produce a 429 before the handler runs.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait. Omitted rather than guessed when the reset instant is unknown."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unhandled failure, including a malformed/non-JSON request body (the body is parsed inside the try block, so a parse failure is not a 400).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "error": "Failed to create atomization"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/atomizations/{id}": {
      "get": {
        "operationId": "getAtomization",
        "summary": "Get an atomization",
        "description": "Returns one atomization, including the generated `data` payload and any `assets`. Requires the `read:atomize` scope. The lookup is organization-scoped, so an id belonging to another organization is indistinguishable from a missing one and returns 404 `not_found`. While `status` is `generating` the `data` object is empty and `assets` is an empty array — poll this endpoint until `status` leaves `generating`.",
        "tags": [
          "Atomizations"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Atomization ID. Must be a UUID; anything else returns 400 `invalid_param`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The atomization",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Correlation id for this request"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "content_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "organization_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "linkedin_carousel",
                            "twitter_thread",
                            "newsletter",
                            "instagram_carousel"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "generating",
                            "review",
                            "published",
                            "archived"
                          ]
                        },
                        "data": {
                          "type": "object",
                          "description": "The generated payload. Free-form JSON whose shape depends on `type` (for example a `linkedin_carousel` carries `title`, `hookSlide`, `contentSlides`, `ctaSlide`; a `twitter_thread` carries `hookTweet`, `contentTweets`, `ctaTweet`; a `newsletter` carries `subjectLine`, `preheader`, `greeting`, `intro`, `keyPoints`, `callToAction`, `signoff` and an optional `psLine`; an `instagram_carousel` adds `caption` and `hashtags`). Empty object until generation finishes."
                        },
                        "assets": {
                          "type": "array",
                          "nullable": true,
                          "items": {},
                          "description": "Generated assets (images, PDFs). Empty array until generation produces any."
                        },
                        "published_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "published_url": {
                          "type": "string",
                          "nullable": true
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The API key lacks the `read:atomize` scope (`insufficient_scope`), the caller's IP is not allow-listed (`ip_not_allowed`), or the organization's subscription/trial is no longer active.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The lookup failed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "error": "Failed to get atomization"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/atomizations/{id}/export": {
      "get": {
        "operationId": "exportAtomization",
        "summary": "Export an atomization",
        "description": "Returns one atomization rendered for the requested `format`. Requires the `read:atomize` scope; the lookup is organization-scoped, so an id from another organization returns 404 `not_found`.\n\n`format=json` (the default) returns the usual JSON envelope — the same record as `GET /atomizations/{id}` minus `content_id` and `organization_id`. `format=markdown` and `format=text` return the rendered document as the raw response body (`text/markdown` / `text/plain`, both `charset=utf-8`) with `Content-Disposition: attachment; filename=\"{type}-{first 8 chars of id}.md|.txt\"` — not the JSON envelope. Plain text is a special case for `twitter_thread` (numbered tweets, no Markdown); every other type is the Markdown rendering with `#`, `*` and `_` stripped.\n\nThe Markdown and text renderers read type-specific fields straight out of the stored payload, so exporting an atomization whose generation has not finished (empty `data`) fails and returns 500 — check that `status` is past `generating` first.",
        "tags": [
          "Atomizations"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Atomization ID. Must be a UUID; anything else returns 400 `invalid_param`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "format",
            "in": "query",
            "description": "Output format. Anything outside the enum returns 400 `invalid_param` on `format`.",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "markdown",
                "text"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The exported atomization. Content type depends on `format`.",
            "headers": {
              "Content-Disposition": {
                "schema": {
                  "type": "string"
                },
                "description": "Set for `markdown` and `text` only: `attachment; filename=\"{type}-{id prefix}.md\"` / `.txt`"
              },
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Correlation id for this request"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "linkedin_carousel",
                            "twitter_thread",
                            "newsletter",
                            "instagram_carousel"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "generating",
                            "review",
                            "published",
                            "archived"
                          ]
                        },
                        "data": {
                          "type": "object",
                          "description": "The generated payload; shape depends on `type`."
                        },
                        "assets": {
                          "type": "array",
                          "nullable": true,
                          "items": {}
                        },
                        "published_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "published_url": {
                          "type": "string",
                          "nullable": true
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string",
                  "description": "Markdown rendering of the atomization (`format=markdown`)"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Plain-text rendering of the atomization (`format=text`)"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The API key lacks the `read:atomize` scope (`insufficient_scope`), the caller's IP is not allow-listed (`ip_not_allowed`), or the organization's subscription/trial is no longer active.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The lookup failed, or the Markdown/text renderer could not read the stored payload (for example an atomization that is still generating).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "error": "Failed to export atomization"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/atomizations/batch": {
      "post": {
        "operationId": "batchCreateAtomizations",
        "summary": "Create several atomizations for one article",
        "description": "Queues up to four channel formats for a single content item in one call. Requires the `write:atomize` scope.\n\nSame gate order as `POST /atomizations`: body validation, then the plan gate (professional or higher), then the 20/hour per organization+user and 50/hour per organization limiters, then billing. `types` must be a non-empty array of at most 4 entries; unknown type values come back as a 400 with `param: \"input\"`.\n\nBilling is one charge for the whole batch, taken lazily just before the first type that actually dispatches — so a batch in which every type is already in flight costs nothing. `overage_incurred` is therefore a single flag for the call, not one per type.\n\nEach type is processed sequentially: a row already at `generating` is reported back unchanged and skipped (no second dispatch), any other row is reset to `generating`, and new rows are inserted. Every dispatched type fires its own `atomization/create` background event, so the 201 means \"queued\", not \"generated\" — poll `GET /atomizations/{id}` for each returned id. There is no transaction across the loop: a mid-loop failure can leave some types queued and the ledger charged, but a retry is free within the same billing period.",
        "tags": [
          "Atomizations"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "content_id",
                  "types"
                ],
                "properties": {
                  "content_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The content item to atomize. Must be a UUID belonging to your organization."
                  },
                  "types": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 4,
                    "description": "Required. 1-4 channel formats to produce.",
                    "items": {
                      "type": "string",
                      "enum": [
                        "linkedin_carousel",
                        "twitter_thread",
                        "newsletter",
                        "instagram_carousel"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Batch queued",
            "headers": {
              "X-Frase-Overage-Incurred": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                },
                "description": "Present only when this call crossed the organization into paid per-article overage"
              },
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Correlation id for this request"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "content_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Echoed back from the request body"
                        },
                        "atomizations": {
                          "type": "array",
                          "description": "One entry per requested type, in request order. Types that were already in flight appear here with their existing id.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "type": {
                                "type": "string",
                                "enum": [
                                  "linkedin_carousel",
                                  "twitter_thread",
                                  "newsletter",
                                  "instagram_carousel"
                                ]
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "generating"
                                ]
                              }
                            }
                          }
                        },
                        "overage_incurred": {
                          "type": "boolean",
                          "description": "True when the batch's single charge crossed the organization into paid per-article overage."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`plan_upgrade_required` — the organization's plan does not include Omni-Channel Atomization (professional or higher); `subscription_inactive` — the subscription is canceled, paused, past due beyond grace, or the trial has expired; or an auth-layer refusal (`insufficient_scope` when the key lacks `write:atomize`, `ip_not_allowed`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "The content does not exist or belongs to another organization. Returned in the plain `{ \"data\": { \"error\": ... } }` envelope, not the structured error object.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "error": "Content not found or does not belong to this organization"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Told apart by `error.code`: `rate_limit_exceeded` (20/hour per organization+user or 50/hour per organization — carries `Retry-After` plus the `X-RateLimit-*` bag), `article_limit_exceeded` (monthly content allowance used up), or `site_article_budget_exceeded` (a per-site article budget is exhausted; only a site admin raising it clears this).",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait. Omitted when the reset instant is unknown."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unhandled failure, including a malformed/non-JSON request body.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "error": "Failed to create batch atomization"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/templates/apply": {
      "post": {
        "operationId": "applyTemplate",
        "summary": "Resolve a template into a ready-to-use outline",
        "description": "Loads one of your templates and returns it resolved into the shape the brief-creation and playbook flows consume: the outline sections mapped to outline entries (each tagged `source: \"template\"`), the template's field defaults, and its boilerplate blocks. Requires the `read:content` scope. Read-only — nothing is created or modified.\n\nThe lookup is organization-scoped and skips soft-deleted rows, and a template that exists but is disabled is refused as well; both refusals come back as 404 in the plain `{ \"data\": { \"error\": ... } }` envelope with the reason in `error` (`Template not found` / `This template is currently disabled`). Note the response does not carry the template's `content_type`.\n\nThe three payload keys are snake_case, but the objects inside them keep the stored camelCase field names.",
        "tags": [
          "Templates"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "template_id"
                ],
                "properties": {
                  "template_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The template to apply. Must be a UUID."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The resolved template",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Correlation id for this request"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "outline": {
                          "type": "array",
                          "description": "The template's sections mapped to outline entries. Empty array when the template stores no sections.",
                          "items": {
                            "type": "object",
                            "description": "An outline section. Field names are camelCase here (unlike the snake_case `ContentOutlineSection` used by the brief endpoints).",
                            "properties": {
                              "heading": {
                                "type": "string"
                              },
                              "level": {
                                "type": "integer",
                                "minimum": 1,
                                "maximum": 6
                              },
                              "keyPoints": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "suggestedWordCount": {
                                "type": "integer"
                              },
                              "generationMode": {
                                "type": "string",
                                "enum": [
                                  "ai",
                                  "manual"
                                ],
                                "description": "Defaults to `ai` when the section does not set one."
                              },
                              "isRequired": {
                                "type": "boolean",
                                "description": "Defaults to true when the section does not set one."
                              },
                              "source": {
                                "type": "string",
                                "enum": [
                                  "template"
                                ],
                                "description": "Always `template` on this path."
                              }
                            }
                          }
                        },
                        "field_defaults": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/TemplateFieldDefaults"
                            }
                          ],
                          "description": "The template's stored defaults, or `{}` when it has none. May also carry Smart Flow keys (`authoritySource`, `blogFormat`, `guideFormat`, `skillLevel`, `blogContext`, `guideContext`)."
                        },
                        "boilerplate_blocks": {
                          "type": "array",
                          "description": "The template's boilerplate blocks, or `[]` when it has none.",
                          "items": {
                            "$ref": "#/components/schemas/BoilerplateBlock"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The API key lacks the `read:content` scope (`insufficient_scope`), the caller's IP is not allow-listed (`ip_not_allowed`), or the organization's subscription/trial is no longer active.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "The template does not exist, is soft-deleted, belongs to another organization, or is disabled. Returned in the plain `{ \"data\": { \"error\": ... } }` envelope, not the structured error object.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "error": "Template not found"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unhandled failure, including a malformed/non-JSON request body.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "error": "Failed to apply template"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/templates/extract": {
      "post": {
        "operationId": "extractTemplate",
        "summary": "Extract a reusable template from a brief or an article",
        "description": "Derives a template from something you already have and saves it. Requires the `write:content` scope.\n\nWith `source_type: \"brief\"` the brief's outline becomes the template sections and the brief's word count, language, country and resolved tone become the field defaults. With `source_type: \"content\"` the article's own brief outline is preferred when it has one; otherwise the HTML (or Markdown) headings of the body are parsed into sections with per-section word counts, falling back to a single `Main Content` section when the body has no headings. Both lookups are organization-scoped and skip soft-deleted rows. Extraction never produces boilerplate blocks — `boilerplate_blocks` always comes back empty.\n\nThis endpoint writes: on success the extracted template is created for your organization (a `Template from {topic or title}` name unless you pass `name`), so 201 means a new template exists and `data.id` is its id. The saved rows are clamped to the content type's allowed word-count range, while the `template` echoed in the response is the pre-clamp extraction — re-read the template via `GET /templates/{id}` if you need the stored values.\n\nOne special case returns 200 instead of 201: if the source yields no outline sections, nothing is saved and the response carries `saved: false` plus a `message` explaining that sections must be added manually.",
        "tags": [
          "Templates"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "source_type",
                  "source_id"
                ],
                "properties": {
                  "source_type": {
                    "type": "string",
                    "enum": [
                      "brief",
                      "content"
                    ],
                    "description": "Required. Whether `source_id` names a brief or a content item."
                  },
                  "source_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The brief or content item to extract from. Must be a UUID."
                  },
                  "name": {
                    "type": "string",
                    "description": "Optional name for the saved template. Truncated to 255 characters. Defaults to the generated `Template from ...` name. Ignored on the unsaved (no sections) path."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extracted but NOT saved — the source produced no outline sections",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Correlation id for this request"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "template": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "description": {
                              "type": "string"
                            },
                            "content_type": {
                              "type": "string",
                              "nullable": true
                            },
                            "outline_sections": {
                              "type": "array",
                              "description": "Always empty on this path.",
                              "items": {
                                "$ref": "#/components/schemas/TemplateSectionDef"
                              }
                            },
                            "boilerplate_blocks": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/BoilerplateBlock"
                              }
                            },
                            "field_defaults": {
                              "$ref": "#/components/schemas/TemplateFieldDefaults"
                            },
                            "source_type": {
                              "type": "string",
                              "enum": [
                                "from_brief",
                                "from_content"
                              ]
                            },
                            "source_content_id": {
                              "type": "string",
                              "format": "uuid",
                              "nullable": true
                            }
                          }
                        },
                        "saved": {
                          "type": "boolean",
                          "enum": [
                            false
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "template": {
                      "name": "Template from Q3 launch post",
                      "description": "Extracted from brief \"Q3 launch post\"",
                      "content_type": null,
                      "outline_sections": [],
                      "boilerplate_blocks": [],
                      "field_defaults": {},
                      "source_type": "from_brief",
                      "source_content_id": null
                    },
                    "saved": false,
                    "message": "Template extracted but not saved — no outline sections found. Add sections manually via POST /templates."
                  }
                }
              }
            }
          },
          "201": {
            "description": "Template extracted and saved",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Correlation id for this request"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Id of the newly created template."
                        },
                        "template": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string",
                              "description": "The stored (trimmed) name."
                            },
                            "description": {
                              "type": "string"
                            },
                            "content_type": {
                              "type": "string",
                              "nullable": true,
                              "description": "The brief's content type, or the article's type, as stored on the source; null when the source has none."
                            },
                            "outline_sections": {
                              "type": "array",
                              "description": "The extracted sections BEFORE the save-time word-count clamping.",
                              "items": {
                                "$ref": "#/components/schemas/TemplateSectionDef"
                              }
                            },
                            "boilerplate_blocks": {
                              "type": "array",
                              "description": "Always empty — extraction does not produce boilerplate.",
                              "items": {
                                "$ref": "#/components/schemas/BoilerplateBlock"
                              }
                            },
                            "field_defaults": {
                              "allOf": [
                                {
                                  "$ref": "#/components/schemas/TemplateFieldDefaults"
                                }
                              ],
                              "description": "Word count, language, country, resolved tone and (content sources) meta title format, as extracted before clamping."
                            },
                            "source_type": {
                              "type": "string",
                              "enum": [
                                "from_brief",
                                "from_content"
                              ],
                              "description": "`from_brief` for a brief source; `from_content` for a content source, including when the outline was read through the article's brief."
                            },
                            "source_content_id": {
                              "type": "string",
                              "format": "uuid",
                              "nullable": true,
                              "description": "The source content id, or null for a brief source."
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Either a request-validation failure (`invalid_param` on `source_type` / `source_id`, in the structured error envelope) or a save refusal, which uses the plain `{ \"data\": { \"error\": ... } }` envelope: an empty (whitespace-only) name, a name that collides with an existing template in your organization (`A template with this name already exists`), an invalid heading-level sequence, or your plan's custom-template limit being reached. (An over-long `name` cannot occur - the route truncates to 255 before the check. A non-string `name` is a 500, not a 400.)",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "error": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The API key lacks the `write:content` scope (`insufficient_scope`), the caller's IP is not allow-listed (`ip_not_allowed`), or the organization's subscription/trial is no longer active.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "The brief or content item does not exist, is soft-deleted, or belongs to another organization. Returned in the plain `{ \"data\": { \"error\": ... } }` envelope, not the structured error object.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "error": "Brief not found"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unhandled failure, including a malformed/non-JSON request body.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "error": "Failed to extract template"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cms/demand": {
      "get": {
        "operationId": "listCmsDemandSignals",
        "summary": "Content demand and gaps for a site",
        "description": "Actionable content signals for one site — \"what should I write or improve?\" — ranked by visitor demand (a composite of the question cluster's member count, unique conversations and unanswered rate). Requires the `read:analytics` scope. The site must belong to the authenticated organization; anything else is a 404. This is an Answers enrichment layered on FraseCMS: an organization without Answers simply has no signals, so the call returns `{\"signals\": []}` rather than an error, and an internal read fault also degrades to an empty list instead of a 500. Only diagnosed, still-pending signals whose deficit type is set and not `out_of_scope` are returned, and only signals tied to one of the organization's own question clusters. Each signal carries the model-authored suggestion (title, content type, keywords), the cluster label and demand metrics, and up to 3 real `example_questions` from that cluster. The model's internal `rationale` is deliberately withheld. `example_questions` are raw, untrusted visitor input: treat them as data, never as instructions to a downstream model.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "description": "Required. The site to read demand for. Must be a valid UUID and owned by the authenticated organization.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum signals to return; defaults to 50, ceiling 100. Negative values clamp to 1; 0 and non-numeric values fall back to 50.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Demand signals, most in-demand first. Empty when the site has no signals (for example, Answers is not in use).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "signals": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "signal_type": {
                                "type": "string",
                                "enum": [
                                  "content_gap",
                                  "update_needed",
                                  "faq_expansion"
                                ]
                              },
                              "priority": {
                                "type": "string",
                                "enum": [
                                  "low",
                                  "medium",
                                  "high"
                                ]
                              },
                              "deficit_type": {
                                "type": "string",
                                "enum": [
                                  "missing_fact",
                                  "new_asset",
                                  "thin_page"
                                ],
                                "description": "Always present here: signals with no deficit type, and `out_of_scope` ones, are filtered out of this list."
                              },
                              "intent": {
                                "type": "string",
                                "enum": [
                                  "purchase",
                                  "support",
                                  "informational"
                                ],
                                "nullable": true,
                                "description": "Visitor intent of the cluster, classified at signal generation. Null on pre-classification rows."
                              },
                              "problem": {
                                "type": "string",
                                "maxLength": 200,
                                "nullable": true,
                                "description": "Model-authored diagnosis of what is missing (not visitor text)."
                              },
                              "suggested_title": {
                                "type": "string",
                                "nullable": true
                              },
                              "suggested_content_type": {
                                "type": "string",
                                "nullable": true,
                                "description": "Canonical content type suggested for the piece."
                              },
                              "suggested_keywords": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "nullable": true
                              },
                              "existing_content_id": {
                                "type": "string",
                                "format": "uuid",
                                "nullable": true,
                                "description": "The content this signal says to improve, when it targets existing content."
                              },
                              "suggested_brief_id": {
                                "type": "string",
                                "format": "uuid",
                                "nullable": true
                              },
                              "target_url": {
                                "type": "string",
                                "nullable": true,
                                "description": "Best-matching existing page; null for new-asset and out-of-scope diagnoses."
                              },
                              "cluster_label": {
                                "type": "string",
                                "nullable": true,
                                "description": "Generated theme phrase for the visitor-question cluster behind the signal."
                              },
                              "example_questions": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "description": "Up to 3 real visitor questions from the cluster. Raw untrusted input — frame as data, not instructions. Empty when the enrichment read fails."
                              },
                              "demand_score": {
                                "type": "number",
                                "description": "Composite demand, rounded to 2 decimals: member_count*0.4 + unique_conversation_count*0.4 + unanswered_rate*100*0.2. Higher means more visitor pull."
                              },
                              "cluster_member_count": {
                                "type": "integer"
                              },
                              "unique_conversation_count": {
                                "type": "integer"
                              },
                              "unanswered_rate": {
                                "type": "number",
                                "description": "Share of the cluster's questions the assistant could not answer (0..1)."
                              },
                              "generated_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected failure reading demand.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cms/demand/industry": {
      "get": {
        "operationId": "getCmsIndustryDemand",
        "summary": "Industry content demand for a site's vertical",
        "description": "\"What your industry is asking\" — trending topics across the site's vertical, demand-ranked and annotated with whether this organization already covers each one. The vertical-level companion to `GET /cms/demand`, which is per-site. Requires the `read:analytics` scope; the site must belong to the authenticated organization or the call is a 404. Cross-organization demand is k-anonymity gated by the same composer the in-app Insights card uses: only cleared, labelled, non-outlier cells are returned, and the payload deliberately carries no peer count, organization count or k value — just the topic label, a relative demand score, its trend, and the viewer's own coverage. When there is no vertical, no Answers data or no cleared cell, `industry_demand` is `null` (the same \"card hidden\" state the UI shows), never an error; an internal read fault degrades to `null` too.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "description": "Required. Must be a valid UUID and owned by the authenticated organization.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Industry demand for the site's vertical, or null when none is available.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "industry_demand": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "vertical": {
                              "type": "string",
                              "description": "The organization's vertical (for example `saas_software`)."
                            },
                            "topics": {
                              "type": "array",
                              "description": "Trending industry topics, demand-ranked.",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "topic_id": {
                                    "type": "string",
                                    "description": "Opaque cell join key (an HMAC of the normalized topic). Stable and safe to store."
                                  },
                                  "topic": {
                                    "type": "string",
                                    "description": "Human-readable topic, labelled only for k-anonymity-cleared, non-outlier cells."
                                  },
                                  "demand_score": {
                                    "type": "number",
                                    "description": "Relative cross-organization demand for the topic. Never a peer or organization count."
                                  },
                                  "demand_trend": {
                                    "type": "number",
                                    "nullable": true,
                                    "description": "Period-over-period change in demand. Computed only for the preview subset of uncovered gap topics (a deliberate privacy/perf bound) - every covered topic and every non-preview topic is null by construction, so null does NOT mean the topic is new."
                                  },
                                  "covered": {
                                    "type": "boolean",
                                    "description": "True when this organization already has a question cluster covering the topic; false means it is a gap."
                                  },
                                  "cluster_id": {
                                    "type": "string",
                                    "format": "uuid",
                                    "nullable": true,
                                    "description": "This organization's own cluster for the topic, or null when it is a gap."
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected failure reading industry demand.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cms/media": {
      "post": {
        "operationId": "uploadCmsMedia",
        "summary": "Upload or rehost an image",
        "description": "Upload an image and get back a public URL you can use in `featured_image`, `og_image` or post body HTML. JSON only — there is no multipart form. Two mutually exclusive shapes: pass `url` to rehost a public HTTPS image onto Frase storage, or pass `data` (base64-encoded image bytes) together with `content_type`. Supplying both is a 400. Requires the `write:content` scope, and the site must belong to the authenticated organization (404 otherwise). Allowed types are `image/jpeg`, `image/png`, `image/webp` and `image/gif`; the maximum size is 2 MB. The rehost fetch is SSRF-guarded (HTTPS only, private and metadata address ranges blocked, redirects rejected, 15 second timeout) and size-bounded while streaming; every fetch failure returns the same generic message so the endpoint cannot be used as a DNS-existence oracle. The storage path is derived from the authenticated organization plus the ownership-checked site and a content hash of the bytes — never from a caller-supplied path. Nothing is persisted in a media table: the response URL is the only record, so store it yourself.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "title": "Rehost from URL",
                    "type": "object",
                    "required": [
                      "site_id",
                      "url"
                    ],
                    "properties": {
                      "site_id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri",
                        "description": "Public HTTPS image URL to fetch and rehost."
                      }
                    }
                  },
                  {
                    "title": "Upload bytes",
                    "type": "object",
                    "required": [
                      "site_id",
                      "data",
                      "content_type"
                    ],
                    "properties": {
                      "site_id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "data": {
                        "type": "string",
                        "format": "byte",
                        "description": "Base64-encoded image bytes. Must decode to at most 2 MB and be non-empty."
                      },
                      "content_type": {
                        "type": "string",
                        "enum": [
                          "image/jpeg",
                          "image/png",
                          "image/webp",
                          "image/gif"
                        ],
                        "description": "MIME type of the bytes. Any `; charset=…` suffix is stripped before the check."
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Image stored.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string",
                          "format": "uri",
                          "description": "Public URL of the stored image."
                        },
                        "content_type": {
                          "type": "string",
                          "description": "The normalized image MIME actually stored."
                        },
                        "bytes": {
                          "type": "integer",
                          "description": "Stored image size in bytes."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. Two shapes reach this status: parameter validation (body is not JSON, `site_id` missing or not a UUID, both `url` and `data` supplied, neither supplied, `data` without `content_type`) returns the standard error envelope; upload validation (unsupported image type, empty image, over 2 MB, or a source URL that could not be fetched or returned a non-2xx) returns a plain message under `data.error`.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "error": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Storage or unexpected failure.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cms/posts/validate": {
      "post": {
        "operationId": "validateCmsPost",
        "summary": "Dry-run a CMS post create",
        "description": "Rehearse `POST /cms/posts` without writing anything. Runs the same structural gates the create path runs — required fields and length caps, scalar shape checks (status enum, HTTPS URLs, ISO 8601 `published_at`), site ownership plus the CMS-enabled and per-site CMS feature gates, the content-type enum and its plan gate, the robots enum, `content_type_config` object/size/per-type schema, slug availability, and whether sanitization would alter your HTML. No rows are written and no images are fetched or rehosted. Requires the `write:content` scope because it rehearses a write and reveals plan and feature-gate state. `valid: true` means every structural gate would pass; taxonomy (authors, categories, tags, FAQs) and `related_post_ids` are not checked here, so a create can still reject a malformed taxonomy payload. Site gates and the slug preview only run once the site is confirmed to belong to your organization, so this endpoint cannot probe another organization's slugs or entitlements — an unowned or unknown `site_id` simply comes back as a `site_id` error rather than a 404. It also returns a content-rules preflight (`rules`) using the same evaluation the publish gate applies, so you can see a block coming before writing; `rules` is advisory and never affects `valid`, and it is `null` when `site_id` or `content` was not a string, or when the preflight itself failed.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "description": "A create-shaped post payload. Only these fields are read; anything else in the body is ignored.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Must be a valid UUID owned by your organization, or it is reported as a `site_id` error."
                  },
                  "title": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "content": {
                    "type": "string",
                    "maxLength": 512000,
                    "description": "HTML body. Also used for the sanitization check and the rules preflight."
                  },
                  "type": {
                    "type": "string",
                    "default": "blog_post",
                    "description": "Canonical content type. Checked against the content-type taxonomy and your plan's allowed CMS types."
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "draft",
                      "published",
                      "scheduled"
                    ]
                  },
                  "slug": {
                    "type": "string",
                    "description": "Used as the slug base; falls back to the title when omitted."
                  },
                  "robots": {
                    "type": "string",
                    "enum": [
                      "index,follow",
                      "noindex,follow",
                      "noindex,nofollow",
                      "index,nofollow"
                    ]
                  },
                  "excerpt": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "seo_title": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "seo_description": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "featured_image": {
                    "type": "string",
                    "format": "uri",
                    "description": "Must be HTTPS."
                  },
                  "canonical_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Must be HTTPS."
                  },
                  "og_image": {
                    "type": "string",
                    "format": "uri",
                    "description": "Must be HTTPS."
                  },
                  "og_title": {
                    "type": "string",
                    "maxLength": 255
                  },
                  "published_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "content_type_config": {
                    "type": "object",
                    "description": "Per-content-type configuration object. Must be a JSON object (not an array), at most 65536 bytes serialized, and must parse against the schema registered for the resolved type."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation ran. Read `valid` for the verdict — a 200 does not mean the input is acceptable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "valid": {
                          "type": "boolean",
                          "description": "True when `errors` is empty, i.e. a create would pass every structural gate."
                        },
                        "errors": {
                          "type": "array",
                          "description": "Every structural failure, collected in one pass.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "field": {
                                "type": "string",
                                "description": "The offending request field, in wire (snake_case) form."
                              },
                              "message": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Non-blocking notes — a taken slug that would be suffixed, or markup that sanitization would strip."
                        },
                        "normalized_slug": {
                          "type": "string",
                          "nullable": true,
                          "description": "The slug a create would use (base slug plus a uniqueness suffix if taken). Null when there is no title or slug, or the site is not owned. A concurrent create could still force a different suffix."
                        },
                        "sanitized": {
                          "type": "boolean",
                          "description": "True when sanitization would strip or alter the submitted HTML."
                        },
                        "rules": {
                          "type": "object",
                          "nullable": true,
                          "description": "Content-rules preflight. Null when `site_id` or `content` was not a string, or the preflight could not run. Advisory only.",
                          "properties": {
                            "overall_status": {
                              "type": "string",
                              "enum": [
                                "pass",
                                "fail",
                                "warning"
                              ],
                              "description": "Worst status across every enabled rule set that applies."
                            },
                            "would_block_publish": {
                              "type": "boolean",
                              "description": "True when `overall_status` is `fail`; a publish would refuse (a draft create still succeeds)."
                            },
                            "needs_force": {
                              "type": "boolean",
                              "description": "True when `overall_status` is `warning`."
                            },
                            "no_rules_configured": {
                              "type": "boolean",
                              "description": "True when no enabled rule set applied at all — a `pass` here means governance was never configured, not that the content cleared any check."
                            },
                            "site_scoped_sets_skipped": {
                              "type": "integer",
                              "description": "Enabled site-scoped rule sets excluded because no site was in scope. On THIS endpoint the preflight only runs when site_id is present, so the value is always 0 - the field exists for shape parity with the shared evaluator."
                            },
                            "violations": {
                              "type": "array",
                              "description": "Every rule that did not pass, flattened across rule sets.",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "rule_name": {
                                    "type": "string"
                                  },
                                  "severity": {
                                    "type": "string",
                                    "enum": [
                                      "error",
                                      "warning",
                                      "info"
                                    ]
                                  },
                                  "message": {
                                    "type": "string"
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The validator itself faulted (the input alone can never cause this).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cms/posts/{id}/autonomous-publish": {
      "post": {
        "operationId": "requestAutonomousCmsPublish",
        "summary": "Request a governed autonomous publish",
        "description": "Ask for a draft to be published through the autonomy gate stack, as opposed to the direct `POST /cms/posts/{id}/publish`. Requires the `write:content` scope and a user-scoped credential — an organization-only key has no actor to stamp on the audit trail and gets a 422. Nothing is published inline: the route validates organization-scoped context and emits the same `cms/autonomous-publish-requested` event the in-app agent uses, so the existing trigger runs the policy dispatcher (action allowlist, site ownership, CMS feature, autonomy level, paused state, approval circuit-breaker, consent, quality verdict, feature flag and organization allowlist, then a credit reserve) inside its own step. With autonomy or its feature flag off — the steady state — the dispatcher denies and the draft is routed to the human review queue instead; that is still a 202, never a 500 and never an ungoverned publish. FraseCMS only: a site that publishes to a connected CMS (WordPress, Webflow) is refused with 409 `destination_not_frase_cms`, because every outcome this endpoint lets you observe is a FraseCMS one. A site sitting in Trash is refused with 409 `site_deleted`. A post with no linked content row is a 422 — use the direct publish endpoint for it. Because the response is 202 and asynchronous, subscribe to the `cms.post.published` and `cms.post.review_requested` webhooks to learn the outcome. Idempotency is surface- and draft-scoped: the request is keyed on the post's content id, the `api` surface, and a digest of the draft body (returned as `draft_revision`). Re-requesting the same unchanged draft within 24 hours is deduplicated and does not run again; editing the draft produces a new revision and is evaluated afresh. An API request is never suppressed by a prior in-app agent request. A draft already waiting in the review queue is re-evaluated but denied `pending_review` — approve or reject it there.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Post ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "description": "Optional provenance so a later \"why did the agent publish this?\" investigation can find the originating signal or brief. An empty body is fine; when a field is present it must be a non-empty string.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "signal_id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 256,
                    "description": "Opaque token, trimmed; control characters and newlines are rejected."
                  },
                  "source_brief_id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 256,
                    "description": "Opaque token, trimmed; control characters and newlines are rejected."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Request accepted and routed to the autonomy gates. Not a publish confirmation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "requested"
                          ]
                        },
                        "post_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "draft_revision": {
                          "type": "string",
                          "description": "16-character digest of the draft body this request was keyed on. Two requests carrying the same value inside the 24 hour window are deduplicated."
                        },
                        "message": {
                          "type": "string",
                          "description": "Human-readable explanation of what happens next and how deduplication applies."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The site's state blocks the request. `site_deleted`: the site is in Trash, so neither a publish nor a review approval could ever land — restore it first. `destination_not_frase_cms`: the site publishes to a connected CMS, so use `POST /cms/posts/{id}/publish` or turn FraseCMS on for the site. Both are fixable by changing the site, which is why they are 409 rather than 422.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        },
                        "code": {
                          "type": "string",
                          "enum": [
                            "site_deleted",
                            "destination_not_frase_cms"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "The request cannot be governed: the credential is not user-scoped, or the post has no linked content row for the gates and quality verdict to evaluate (use the direct publish endpoint instead).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The site's CMS state could not be verified. Safe to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cms/posts/{id}/performance": {
      "get": {
        "operationId": "getCmsPostPerformance",
        "summary": "Performance for one CMS post",
        "description": "Quality scores, Search Console metrics and a health grade for a single post. Requires the `read:analytics` scope; the post is loaded by id together with your organization, so another organization's post is an ordinary 404. Scores resolve by precedence — the site's latest completed audit page matching the post's slug, then the content URL registry mirror (which covers posts the latest crawl missed), then the generation-time scores on the linked content row; `scores.source` names the dominant source, though individual pillars can still fall through independently. `technical_score`, `content_score`, `content_decay_score`, `word_count` and `issue_count` come only from an audit page and are null without one. Search metrics are Search Console data for the site, summed and averaged over the trailing 28 days and matched to the post's slug; `search` is null when there is no matching data. `health_status` is graded from the overall score and the search position, and is `no_data` when neither is available — a post with no computable score is no longer graded as healthy. `demand` is an optional Answers enrichment and is null when Answers is off, the post has no linked content, or no signal matches. `published_url` is resolved from the site's FraseCMS settings and is only present for published posts.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Post ID. Must be a valid UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Post performance snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "post_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "slug": {
                          "type": "string"
                        },
                        "title": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "published",
                            "scheduled"
                          ],
                          "description": "The post row's own status (localPostStatusEnum). `scheduled` rows sit here until the publisher cron flips them."
                        },
                        "published_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "published_url": {
                          "type": "string",
                          "nullable": true,
                          "description": "Live URL built from the site's FraseCMS settings. Null unless the post is published (or the site has no CMS settings row)."
                        },
                        "scores": {
                          "type": "object",
                          "properties": {
                            "seo_score": {
                              "type": "number",
                              "nullable": true
                            },
                            "geo_score": {
                              "type": "number",
                              "nullable": true
                            },
                            "eeat_score": {
                              "type": "number",
                              "nullable": true
                            },
                            "aeo_score": {
                              "type": "number",
                              "nullable": true,
                              "description": "Audit or registry only — never falls back to generation scores."
                            },
                            "overall_score": {
                              "type": "number",
                              "nullable": true,
                              "description": "The audit page's overall score, or one derived from the generation scores when there is no audit page."
                            },
                            "technical_score": {
                              "type": "number",
                              "nullable": true,
                              "description": "From the matching audit page only."
                            },
                            "content_score": {
                              "type": "number",
                              "nullable": true,
                              "description": "From the matching audit page only."
                            },
                            "content_decay_score": {
                              "type": "number",
                              "nullable": true,
                              "description": "From the matching audit page only."
                            },
                            "word_count": {
                              "type": "integer",
                              "nullable": true,
                              "description": "From the matching audit page only."
                            },
                            "issue_count": {
                              "type": "integer",
                              "nullable": true,
                              "description": "Issues recorded on the matching audit page; null without one."
                            },
                            "source": {
                              "type": "string",
                              "enum": [
                                "audit",
                                "registry",
                                "generation"
                              ],
                              "nullable": true,
                              "description": "Dominant provenance of the scores. Null when no source produced any."
                            }
                          }
                        },
                        "search": {
                          "type": "object",
                          "nullable": true,
                          "description": "Search Console metrics for the trailing window, or null when no row matches the post's slug.",
                          "properties": {
                            "clicks": {
                              "type": "integer"
                            },
                            "impressions": {
                              "type": "integer"
                            },
                            "ctr": {
                              "type": "number",
                              "description": "Average click-through rate over the window, rounded to 3 decimals. 0 when the underlying average is absent."
                            },
                            "position": {
                              "type": "number",
                              "description": "Average position over the window, rounded to 1 decimal. 0 means no position was recorded, not rank zero."
                            },
                            "window_days": {
                              "type": "integer",
                              "description": "Days of Search Console data aggregated (28)."
                            }
                          }
                        },
                        "health_status": {
                          "type": "string",
                          "enum": [
                            "healthy",
                            "needs_attention",
                            "critical",
                            "no_data"
                          ],
                          "description": "Graded from the overall score plus the search position. `no_data` when there is no computable score and no recorded position."
                        },
                        "observed_deliveries": {
                          "type": "integer",
                          "description": "Count of bot-excluded human deliveries recorded for this post."
                        },
                        "demand": {
                          "type": "object",
                          "nullable": true,
                          "description": "Answers demand for the visitor-question cluster this post answers. Null when Answers is off, the post has no linked content, or no signal matches.",
                          "properties": {
                            "demand_score": {
                              "type": "number",
                              "description": "Composite demand, rounded to 2 decimals: member_count*0.4 + unique_conversation_count*0.4 + unanswered_rate*100*0.2."
                            },
                            "unanswered_rate": {
                              "type": "number",
                              "description": "Share of the cluster's matched questions still unanswered (0..1)."
                            },
                            "cluster_member_count": {
                              "type": "integer"
                            },
                            "unique_conversation_count": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected failure reading performance. The message is sanitized.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/content/resolve": {
      "post": {
        "operationId": "resolveContentByName",
        "summary": "Resolve a content name to a content ID",
        "description": "Look up content in your organization by exact title, case-insensitively, so an agent can turn a human-supplied name into the `content_id` every other content endpoint needs. Requires the `read:content` scope (a write-only key cannot enumerate titles) and a plan with content optimization; orgs below that plan get 403. Read-only, no side effects.\n\nThe match is exact-but-case-insensitive (`lower(title) = lower(name)`), scoped to your organization, and excludes trashed content. It is NOT a fuzzy or partial search. Always branch on `status`:\n- `ok` — exactly one match; `content_id` is returned and nothing else.\n- `not_found` — no match; only `status` is present.\n- `needs_disambiguation` — two or more matches; `candidates` (at most 10), `total_matches`, and `truncated` are returned. When `truncated` is true, `total_matches` is a LOWER BOUND (11), not a real count: at most 11 rows are ever read, so treat it as \"at least this many\" and ask for a more specific name rather than paginating. Candidates are ordered newest-updated first.\n\n`name` is trimmed, must be 1-255 characters and must not contain control characters (any byte below 0x20, or 0x7F) — those are rejected with 400 rather than smuggled into audit logs.\n\nCORS preflight is supported (OPTIONS returns 204; allowed methods POST, OPTIONS; allowed headers Content-Type, X-API-KEY).",
        "tags": [
          "Content"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255,
                    "description": "Required. The content title to resolve. Trimmed before matching; must be 1-255 characters after trimming and must not contain control characters."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resolution result. Always 200 — a name that matches nothing is `status: not_found`, not a 404.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "not_found",
                            "needs_disambiguation"
                          ],
                          "description": "Which of the three result shapes this is. Always present."
                        },
                        "content_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Present only when status is `ok`: the single matching content row."
                        },
                        "candidates": {
                          "type": "array",
                          "description": "Present only when status is `needs_disambiguation`. At most 10 entries, ordered by most recently updated first.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "title": {
                                "type": "string"
                              },
                              "slug": {
                                "type": "string",
                                "nullable": true
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "draft",
                                  "generating",
                                  "review",
                                  "published",
                                  "archived"
                                ]
                              },
                              "word_count": {
                                "type": "integer",
                                "description": "0 when the row has no recorded word count."
                              },
                              "updated_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          }
                        },
                        "total_matches": {
                          "type": "integer",
                          "description": "Present only when status is `needs_disambiguation`. Exact when `truncated` is false; a lower bound of 11 when `truncated` is true."
                        },
                        "truncated": {
                          "type": "boolean",
                          "description": "Present only when status is `needs_disambiguation`. True when more than 10 rows matched, in which case `total_matches` is a lower bound and you should re-ask with a more specific name."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Either the plan gate or the credential. The plan gate (org lacks content optimization) answers with the data-wrapped shape `{\"data\": {\"error\": \"Content optimization requires <plan> plan or higher.\"}}`. Credential refusals (missing `read:content` scope, IP not allowlisted, expired trial) answer with the standard error envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "error": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "example": "Failed to resolve content name"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/content/summary": {
      "get": {
        "operationId": "getContentSummary",
        "summary": "Get content counts by status",
        "description": "A single lightweight roll-up of how much content your organization has in each workflow state — cheaper than listing content and counting client-side, and the usual first call when an agent needs to orient itself. Requires the `read:content` scope. Read-only, no side effects.\n\nCounts are org-scoped and exclude trashed (soft-deleted) content. `status_counts` contains only the statuses that actually have rows, in no guaranteed order — a status with zero rows is omitted entirely, so do not rely on all five appearing. `total` is the sum of the returned counts. There are no query parameters and no pagination.\n\nCORS preflight is supported (OPTIONS returns 204; allowed methods GET, OPTIONS; allowed headers Content-Type, X-API-KEY).",
        "tags": [
          "Content"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Content status counts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status_counts": {
                          "type": "array",
                          "description": "One entry per status that has at least one non-trashed content row.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "draft",
                                  "generating",
                                  "review",
                                  "published",
                                  "archived",
                                  "unknown"
                                ],
                                "description": "Workflow status. `unknown` is a defensive fallback for a row with no status."
                              },
                              "count": {
                                "type": "integer"
                              }
                            }
                          }
                        },
                        "total": {
                          "type": "integer",
                          "description": "Sum of every count above — all non-trashed content in the organization."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The count query failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "description": "Either `Failed to get content status counts` (from the query layer) or `Failed to get content summary` (unexpected failure)."
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/content/{id}/restore": {
      "post": {
        "operationId": "restoreTrashedContent",
        "summary": "Restore trashed content",
        "description": "Bring a soft-deleted (trashed) content row back out of the Trash. Requires the `write:content` scope. Takes no request body.\n\nOnly content that is currently IN the Trash can be restored: the lookup requires the row to be org-scoped and to have a deletion timestamp, so a live (never-deleted) id, an already-restored id, and another organization's id are all indistinguishable 404s. Restoring is idempotent only in the sense that a second call 404s — it will not re-restore.\n\nThere is a hard 30-day customer restore window measured from the deletion timestamp. Once 30 or more full days have passed the endpoint answers 410 and the row can only be recovered by Frase support. The restore clears the deletion markers, bumps the row's `updated_at`, and may bring linked companion records back with it; those companions are not reported in this response.\n\n`title` and `status` in the response are the values the row already had — restoring does not change a content row's workflow status. This endpoint does NOT run the content-rules gate and never returns 422 or a `retry_with_force` hint; that behaviour belongs to the CMS post version-restore endpoint, which republishes through the update path.\n\nCORS preflight is supported (OPTIONS returns 204; allowed methods POST, OPTIONS; allowed headers Content-Type, X-API-KEY, token).",
        "tags": [
          "Content"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "ID of the trashed content to restore",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Content restored",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "title": {
                          "type": "string",
                          "description": "The restored row's title, as it was in the Trash."
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "generating",
                            "review",
                            "published",
                            "archived"
                          ],
                          "description": "Workflow status, unchanged by the restore."
                        },
                        "restored": {
                          "type": "boolean",
                          "description": "Always true on a 200."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "410": {
            "description": "Past the 30-day customer restore window — permanent, retrying will not help.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "example": "Content is past the 30-day restore window. Contact support for assistance."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The restore failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "example": "Failed to restore content"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/optimizations/{id}/republish": {
      "post": {
        "operationId": "republishOptimizationContent",
        "summary": "Accept a suggestion application and re-publish",
        "description": "Accept a reviewable suggestion application for an optimization and push the updated content back to the CMS destination it was originally published to. The remote post is UPDATED in place — never re-created — so the existing URL and external ID are preserved. Requires the `write:content` scope and a plan with content optimization.\n\nBoth `content_id` and `application_id` must be supplied and must line up with the optimization named in the path: the optimization's content must equal `content_id` (400 `invalid_request` otherwise), and the application must belong to the same organization, optimization and content (404 otherwise). The CMS destination and remote post id are read off the content row — you cannot supply them.\n\nThe application must be in `reviewable` state. An `accepted` or `reverted` application is 409 `already_terminal`; any other state is 409 `invalid_state`. On success the application is moved to `accepted`, and a content row sitting in `review` is moved to `published`.\n\nThis is an unattended caller, so drift is never forced: if the post changed in the CMS since Frase last published it, the request is refused with 409 `REMOTE_CONTENT_CHANGED` and must be resolved in the Frase app. Content rule violations and Trust & Safety blocks refuse with 422. A CMS integration that needs reconnecting refuses with 401 code `UNAUTHORIZED` (data-wrapped) - fix the connection in the Frase app. Rate limits apply on two axes — a per-user hourly generate budget (30/hour) checked before any work, and a per-organization re-publish limiter (5/minute) inside the publish path; both answer 429 with code `RATE_LIMITED`.\n\nStatus codes are chosen so that only genuinely retryable failures land in the 5xx range: 409, 410 and 422 refusals never self-clear and must not be retried. Every failure body except the 400 parameter errors, the 404s, and the plan-gate 403 carries a machine-readable `code` alongside `error`.\n\nCORS preflight is supported (OPTIONS returns 204; allowed methods POST, OPTIONS; allowed headers Content-Type, X-API-KEY, token).",
        "tags": [
          "Optimizations"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Optimization ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "content_id",
                  "application_id"
                ],
                "properties": {
                  "content_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. Must be the content the optimization belongs to."
                  },
                  "application_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The suggestion application to accept. Must belong to this optimization and content, and be in `reviewable` state."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Re-published. The application is now `accepted`, and content that was in `review` is now `published`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "destination": {
                          "type": "string",
                          "enum": [
                            "frase_cms",
                            "wordpress",
                            "webflow",
                            "sanity",
                            "wix"
                          ],
                          "description": "The CMS the post was updated on, resolved from the content row."
                        },
                        "url": {
                          "type": "string",
                          "nullable": true,
                          "description": "Live URL of the updated post, when the adapter reports one."
                        },
                        "external_id": {
                          "type": "string",
                          "nullable": true,
                          "description": "The remote post's id in the destination CMS, when the adapter reports one."
                        },
                        "live_publish_failed": {
                          "type": "boolean",
                          "description": "Webflow only, present only when true. The CMS item was updated but Webflow refused the site-level publish, so the live page still serves the OLD body and `url` is null. The write itself succeeded, which is why this is a 200 and not an error. See `live_publish_message`."
                        },
                        "live_publish_message": {
                          "type": "string",
                          "description": "Present alongside `live_publish_failed`: what still has to happen for the update to go live, including Webflow's own sentence where it gave a usable one."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request. A missing or non-UUID `id`, `content_id` or `application_id` returns the standard validation envelope. Two request-shaped refusals instead return the data-wrapped shape `{\"data\": {\"error\": \"...\", \"code\": \"...\"}}`: `invalid_request` (the optimization is not for the supplied `content_id`) and `NO_EXTERNAL_POST_ID` (the content has no resolvable CMS destination or remote post id, so there is nothing to update).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "error": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Two body shapes share this status: the auth layer's structured Error envelope (bad or missing API key), and — AFTER successful key auth — the handler's data-wrapped shape with code `UNAUTHORIZED` when the CMS integration itself needs reconnecting (e.g. a disconnected WordPress connection; no live integration record). A generated client must not assume the structured shape.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "error": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Either the plan gate or the credential. The plan gate (org lacks content optimization) answers with the data-wrapped shape `{\"data\": {\"error\": \"Content optimization requires <plan> plan or higher.\"}}`. Credential refusals (missing `write:content` scope, IP not allowlisted, expired trial) answer with the standard error envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "error": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "The optimization, the content, or the suggestion application was not found in your organization (or the content was trashed). All four not-found cases share this one envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "A conflict that will not clear on retry. `code` is one of: `already_terminal` (application already accepted or reverted), `invalid_state` (application is not `reviewable`), `REMOTE_CONTENT_CHANGED` (the post was edited in the CMS since Frase last published it — resolve it in the Frase app; an API key can never force past this), `site_deleted` (the site was moved to Trash after this content was linked to it), or `REVIEW_REQUIRED` (the destination requires approval before this can go out again).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        },
                        "code": {
                          "type": "string",
                          "enum": [
                            "already_terminal",
                            "invalid_state",
                            "REMOTE_CONTENT_CHANGED",
                            "site_deleted",
                            "REVIEW_REQUIRED"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "410": {
            "description": "`REMOTE_POST_MISSING` — the remote post existed and has since been deleted in the CMS, so there is nothing left to update. Non-retryable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        },
                        "code": {
                          "type": "string",
                          "enum": [
                            "REMOTE_POST_MISSING"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "A deterministic content or configuration refusal — retrying the same content will always fail. `code` is one of: `rules_blocked` (the content fails one or more rule sets), `content_safety_blocked` (Trust & Safety refused the body being pushed), or `UNKNOWN_CONTENT_TYPE` (the content's type is not publishable to this destination).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        },
                        "code": {
                          "type": "string",
                          "enum": [
                            "rules_blocked",
                            "content_safety_blocked",
                            "UNKNOWN_CONTENT_TYPE"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. The route's own limiters answer with the data-wrapped shape `{\"data\": {\"error\": \"...\", \"code\": \"RATE_LIMITED\"}}` and carry no `Retry-After` header — the retry delay is stated in the message. Two limiters can produce it: a per-user generate budget of 30 per hour, checked before any work, and a per-organization re-publish limiter of 5 per minute inside the publish path. API-key burst, sustained and monthly limits answer earlier with the standard error envelope and a `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`UNKNOWN` — an unclassified failure. Safe to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        },
                        "code": {
                          "type": "string",
                          "enum": [
                            "UNKNOWN"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "A genuine gateway failure, worth retrying. `UPDATE_FAILED` - the CMS rejected or could not complete the update (also covers an unsupported provider or a broken connection).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        },
                        "code": {
                          "type": "string",
                          "enum": [
                            "UPDATE_FAILED"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "504": {
            "description": "`TIMEOUT` — the CMS did not respond in time. Retryable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        },
                        "code": {
                          "type": "string",
                          "enum": [
                            "TIMEOUT"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/auto-optimization/toggle": {
      "post": {
        "operationId": "toggleAutoOptimization",
        "summary": "Turn auto-optimization on or off for a site",
        "description": "Enable or disable auto-optimization for one site, and optionally reconfigure which suggestion types are auto-applied and the confidence threshold they must clear. Requires the `write:optimizations` scope.\n\n`site_id` and `enabled` are always required. `auto_apply_types` and `confidence_threshold` are optional and are only written when supplied — omitting them leaves the site's stored values untouched, so disabling never discards a configuration you can re-enable later.\n\nThe response echoes the RAW PERSISTED site settings, not the effective policy. GET /auto-optimization/status reports the effective values, which may be narrower because a saved workspace policy (Content Guard) intersects the allowed types and takes the stricter threshold. An empty `auto_apply_types` means nothing is applied automatically and every suggestion waits for review.\n\nA site that does not exist in your organization, or is in the Trash, is reported as a 400 (`Site not found`) rather than a 404. Invalid suggestion types and an out-of-range threshold are also 400s, with the message naming the valid values.\n\nCORS preflight is supported (OPTIONS returns 204; allowed methods POST, OPTIONS; allowed headers Content-Type, X-API-KEY).",
        "tags": [
          "Optimizations"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "enabled"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The site to configure. Must belong to your organization and not be trashed."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Required. True turns auto-optimization on for the site; false pauses it while preserving the stored types and threshold."
                  },
                  "auto_apply_types": {
                    "type": "array",
                    "description": "Optional. Suggestion types eligible for automatic application. Only written when supplied; an empty array means nothing is auto-applied. Any value outside the enum rejects the whole request.",
                    "items": {
                      "type": "string",
                      "enum": [
                        "add_section",
                        "expand_section",
                        "update_stats",
                        "add_faq",
                        "improve_meta",
                        "add_internal_links",
                        "update_heading"
                      ]
                    }
                  },
                  "confidence_threshold": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Optional. Minimum confidence (0-100) a suggestion must reach to be auto-applied. Only written when supplied."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Site settings persisted. Values are the raw stored site settings, not the workspace-narrowed effective policy.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "site_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "enabled": {
                          "type": "boolean",
                          "description": "Auto-optimization toggle as now stored on the site; false when the column is unset."
                        },
                        "auto_apply_types": {
                          "type": "array",
                          "description": "Suggestion types now stored on the site. Empty array when none are configured.",
                          "items": {
                            "type": "string"
                          }
                        },
                        "auto_apply_confidence_threshold": {
                          "type": "number",
                          "description": "Confidence threshold now stored on the site. Defaults to 80 when the column is unset."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Parameter-shape problems — `site_id` missing, not a string, or not a UUID; `enabled` missing or not a boolean; `auto_apply_types` not an array of strings; `confidence_threshold` not a number — return the standard validation envelope with `param` naming the field. Refusals from the update itself instead return the data-wrapped shape `{\"data\": {\"error\": \"...\"}}` with no `code`: `Site not found` (unknown, other-org, or trashed site), `Invalid auto-apply types: ... Valid types: ...`, `Confidence threshold must be between 0 and 100`, `Failed to update site`, or `Failed to toggle auto-optimization` (the core's own catch - a DB fault during the update lands HERE, not at 500).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "error": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The request body was not valid JSON, or the route itself faulted. (A DB fault inside the update is a 400 - see above.)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "example": "Failed to toggle auto-optimization"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/opportunities/{id}": {
      "get": {
        "operationId": "getOpportunity",
        "summary": "Get an opportunity",
        "description": "Full detail for a single opportunity, resolved across the source tables by the id prefix: `gap_` reads content_gap_opportunities, `prog_` reads programmatic_opportunities, `decay_` reads performance_alerts. The id is `<prefix>_<uuid>`; a malformed UUID suffix is refused with 400 (not 500). A bare UUID with no prefix is tolerated and resolves as a gap opportunity. Everything the list route returns is present, plus the detail-only fields `source_id`, `source_table`, `traffic_source`, `estimated_clicks`, `existing_content_url`, `parameters`, `suggested_brief_id`, `brief_status`, `content_id`, `content_status` and `methodology` (the transparency block: data sources, analysis, calculation, assumptions, confidence factors). Requires the `read:opportunities` scope. Reads are org-scoped, so an id belonging to another organization returns 404, indistinguishable from one that does not exist. A gap row whose keyword fails the shared junk-keyword filter also resolves to 404 - the same rows the hub hides are unavailable here, so an agent cannot plan off a row a human would never see. `relevance` is derived at read time (cluster fit + first-party evidence + never-write-about terms) and is null when no verdict was derived.\n\n### 2026-09-07 - decay_ ids resolve decay alerts only\n\nA `decay_<id>` whose alert is a ranking or traffic alert now answers 404. The list never emitted such an id (it lists decay alerts only), and the detail gives the list's answer for every source.\n\n### 2026-09-07 - closed rows report their status\nA completed or dismissed programmatic row and a resolved decay alert still resolve by their id, and now carry that status (`completed` or `dismissed`) where they carried `new`; a resolved alert is closed whoever resolved it, and reads `dismissed` only when the dismissal wrote its own default words. The lists never show them; a stored id reads its final state.",
        "tags": [
          "Opportunities"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Composite opportunity ID: gap_UUID, prog_UUID or decay_UUID.",
            "schema": {
              "type": "string",
              "example": "gap_3f1c2b8e-9a4d-4e17-8b2f-0c5d6e7a8b90"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Opportunity detail",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Composite id, echoed back (gap_/prog_/decay_ + UUID)."
                        },
                        "source_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Primary key in the source table."
                        },
                        "source_table": {
                          "type": "string",
                          "enum": [
                            "content_gap_opportunities",
                            "programmatic_opportunities",
                            "performance_alerts"
                          ]
                        },
                        "title": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "gsc",
                            "competitor",
                            "programmatic",
                            "decay"
                          ]
                        },
                        "action": {
                          "type": "string",
                          "enum": [
                            "update",
                            "create",
                            "batch"
                          ]
                        },
                        "view": {
                          "type": "string",
                          "enum": [
                            "quick-wins",
                            "growth",
                            "strategic"
                          ]
                        },
                        "scores": {
                          "type": "object",
                          "properties": {
                            "overall": {
                              "type": "number",
                              "description": "0-100 weighted composite."
                            },
                            "effort": {
                              "type": "object",
                              "properties": {
                                "score": {
                                  "type": "number",
                                  "description": "0-100, lower = easier."
                                },
                                "factors": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                }
                              }
                            },
                            "impact": {
                              "type": "object",
                              "properties": {
                                "score": {
                                  "type": "number",
                                  "description": "0-100, higher = more valuable."
                                },
                                "factors": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                }
                              }
                            },
                            "speed": {
                              "type": "object",
                              "properties": {
                                "score": {
                                  "type": "number",
                                  "description": "0-100, higher = faster to rank."
                                },
                                "factors": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                }
                              }
                            },
                            "strategic": {
                              "type": "object",
                              "properties": {
                                "score": {
                                  "type": "number",
                                  "description": "0-100, higher = more strategic value."
                                },
                                "factors": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                }
                              }
                            }
                          }
                        },
                        "confidence": {
                          "type": "string",
                          "enum": [
                            "high",
                            "medium",
                            "low"
                          ]
                        },
                        "relevance": {
                          "type": "object",
                          "nullable": true,
                          "description": "How far this topic travels. Same projection as the list route (bucket + reason only). off_strategy rows are excluded from default lists; uncertain rows are demoted and never auto-publish.",
                          "properties": {
                            "bucket": {
                              "type": "string",
                              "enum": [
                                "confident",
                                "uncertain",
                                "off_strategy"
                              ]
                            },
                            "reason": {
                              "type": "string",
                              "description": "Plain-language clause. Reads `matches one of your never-write-about terms` when the off_strategy verdict came from an excluded term."
                            }
                          }
                        },
                        "estimated_traffic": {
                          "type": "integer",
                          "description": "Estimated monthly visits."
                        },
                        "traffic_source": {
                          "type": "string",
                          "enum": [
                            "gsc_clicks",
                            "search_volume",
                            "none"
                          ],
                          "description": "Where the traffic estimate came from."
                        },
                        "estimated_clicks": {
                          "type": "integer"
                        },
                        "search_volume": {
                          "type": "integer",
                          "nullable": true
                        },
                        "current_position": {
                          "type": "number",
                          "nullable": true
                        },
                        "difficulty": {
                          "type": "integer",
                          "nullable": true
                        },
                        "page_count": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Programmatic rows only: how many pages the batch would produce."
                        },
                        "parameters": {
                          "type": "array",
                          "nullable": true,
                          "description": "Programmatic rows only: the per-page parameter set. Free-form objects.",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        },
                        "programmatic_type": {
                          "type": "string",
                          "nullable": true,
                          "enum": [
                            "location",
                            "comparison",
                            "integration",
                            "custom"
                          ]
                        },
                        "site_id": {
                          "type": "string",
                          "nullable": true
                        },
                        "site_domain": {
                          "type": "string",
                          "nullable": true
                        },
                        "existing_content_id": {
                          "type": "string",
                          "nullable": true
                        },
                        "existing_content_title": {
                          "type": "string",
                          "nullable": true
                        },
                        "existing_content_url": {
                          "type": "string",
                          "nullable": true
                        },
                        "cluster_id": {
                          "type": "string",
                          "nullable": true
                        },
                        "cluster_name": {
                          "type": "string",
                          "nullable": true
                        },
                        "competitors": {
                          "type": "array",
                          "nullable": true,
                          "items": {
                            "type": "object",
                            "properties": {
                              "domain": {
                                "type": "string"
                              },
                              "position": {
                                "type": "integer",
                                "nullable": true
                              },
                              "url": {
                                "type": "string",
                                "nullable": true
                              }
                            }
                          }
                        },
                        "suggested_brief_id": {
                          "type": "string",
                          "nullable": true,
                          "description": "Set once a brief has been minted from this opportunity. A non-null value means POST /opportunities/{id}/brief will refuse with 409."
                        },
                        "brief_status": {
                          "type": "string",
                          "nullable": true,
                          "enum": [
                            "draft",
                            "research_preview",
                            "pending",
                            "ready",
                            "failed"
                          ]
                        },
                        "content_id": {
                          "type": "string",
                          "nullable": true
                        },
                        "content_status": {
                          "type": "string",
                          "nullable": true,
                          "enum": [
                            "draft",
                            "generating",
                            "review",
                            "published",
                            "archived"
                          ]
                        },
                        "methodology": {
                          "type": "object",
                          "nullable": true,
                          "description": "Transparency block: how the estimate was produced.",
                          "properties": {
                            "data_sources": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "type": {
                                    "type": "string",
                                    "enum": [
                                      "gsc",
                                      "competitor_crawl",
                                      "keyword_research",
                                      "brand_settings",
                                      "site_audit"
                                    ]
                                  },
                                  "name": {
                                    "type": "string"
                                  },
                                  "description": {
                                    "type": "string"
                                  },
                                  "last_updated": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                  },
                                  "quality": {
                                    "type": "string",
                                    "enum": [
                                      "verified",
                                      "estimated",
                                      "inferred"
                                    ]
                                  }
                                }
                              }
                            },
                            "analysis": {
                              "type": "object",
                              "description": "What was analyzed. Keys are present only when the producer had them.",
                              "properties": {
                                "competitorsAnalyzed": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                },
                                "pagesAnalyzed": {
                                  "type": "integer"
                                },
                                "keywordsAnalyzed": {
                                  "type": "integer"
                                },
                                "timeRange": {
                                  "type": "string"
                                }
                              }
                            },
                            "calculation": {
                              "type": "object",
                              "properties": {
                                "formula": {
                                  "type": "string"
                                },
                                "inputs": {
                                  "type": "object",
                                  "additionalProperties": {
                                    "oneOf": [
                                      {
                                        "type": "number"
                                      },
                                      {
                                        "type": "string"
                                      }
                                    ]
                                  }
                                },
                                "result": {
                                  "type": "number"
                                },
                                "unit": {
                                  "type": "string"
                                }
                              }
                            },
                            "assumptions": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "confidence_factors": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "factor": {
                                    "type": "string"
                                  },
                                  "value": {
                                    "type": "string"
                                  },
                                  "impact": {
                                    "type": "string",
                                    "enum": [
                                      "positive",
                                      "negative",
                                      "neutral"
                                    ]
                                  }
                                }
                              }
                            }
                          }
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "new",
                            "reviewed",
                            "in_progress",
                            "completed",
                            "dismissed",
                            "auto_resolved",
                            "unknown"
                          ],
                          "description": "`unknown` is a read-time value for a DB string outside the known set; no row is created with it."
                        },
                        "detected_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "last_analyzed_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Malformed opportunity id - missing, shorter than 5 characters, or a suffix that is not a valid UUID (`Invalid opportunity ID format. Expected: gap_UUID, prog_UUID, or decay_UUID`). Note the resolver is lenient about the prefix itself: a bare UUID (no prefix) passes the guard and resolves as a gap opportunity. Not retryable. This body is the plain `{ \"data\": { \"error\": \"...\" } }` envelope, not the structured Error object.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Lookup failed (`Failed to get opportunity`). Plain `{ \"data\": { \"error\": \"...\" } }` envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/opportunities/{id}/brief": {
      "post": {
        "operationId": "createOpportunityBrief",
        "summary": "Create a brief from an opportunity",
        "description": "Accept a gap opportunity: mint a content brief from it and attach the brief to the row. Requires the `write:opportunities` scope AND an API key linked to a user (the linked user becomes the brief's `created_by`); an unlinked key is refused 403 before any lookup, so it never learns whether the id exists.\n\nOnly `gap_` ids are accepted. `prog_` ids return 400 (programmatic opportunities use batch generation) and `decay_` ids return 400 (use the update action). A `gap_` id whose suffix is not a valid UUID returns 400.\n\nOrdering is load-bearing and observable. The opportunity is fetched first, so a 404 costs nothing and never mutates the row. The monthly brief allowance is checked BEFORE the row is claimed, so an at-cap organization is refused with the row untouched rather than left stranded at `in_progress`. Only then is the row claimed with a conditional UPDATE to `status = in_progress`; that single statement is also the closed-check and the concurrency check, so a dismissed/completed row, a row that already carries a `suggested_brief_id`, and a row another live accept is holding all lose it and get 409. Any failure after the claim releases it and restores the prior status.\n\nBilling and metering: one accepted call consumes one brief from the organization's monthly brief allowance (calendar-month window; imported briefs and regeneration forks do not count). When the allowance is exhausted the call returns 429 with code `brief_limit_exceeded` and a truthful `Retry-After` giving the seconds until the monthly window rolls - this is a QUOTA, not a burst limit, so retrying before that instant cannot succeed and an SDK's default backoff must not re-hammer it. When the organization's subscription is canceled, paused, past due beyond grace, or its trial has expired, the call returns 403 with code `subscription_inactive` instead. A topic matching one of the organization's never-write-about terms returns 422 and no quota is consumed.\n\nSuccess is 201 and asynchronous: the brief row exists immediately with status `pending`, and outline generation plus full research run in the background. Poll `GET /api/v1/briefs/{brief_id}` (or `/briefs/{brief_id}/status`) for readiness. The brief inherits the opportunity's cluster (`cluster_id`) and site, and its relevance bucket rides along - anything but `confident` is held for review at dispatch rather than auto-published.",
        "tags": [
          "Opportunities"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Gap opportunity ID (gap_UUID). Other prefixes are rejected with 400.",
            "schema": {
              "type": "string",
              "example": "gap_3f1c2b8e-9a4d-4e17-8b2f-0c5d6e7a8b90"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Brief creation started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "brief_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "The new brief. Status is `pending` until outline generation and research finish."
                        },
                        "topic": {
                          "type": "string",
                          "description": "The brief's topic: the opportunity title with the `New Article: ` / `Update: ` prefix stripped, falling back to `Opportunity <first 8 chars of source_id>` when the title is empty."
                        },
                        "opportunity_id": {
                          "type": "string",
                          "description": "The composite id this brief was created from, echoed back."
                        },
                        "message": {
                          "type": "string",
                          "description": "Fixed guidance string: `Brief creation started. Use GET /api/v1/briefs/{brief_id} to check status.`"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Rejected before any work. Two body shapes: the structured Error object (code `invalid_param`, `param: \"id\"`) for a missing/too-short id, a non-`gap_` prefix, or a non-UUID suffix; and the plain `{ \"data\": { \"error\": \"...\" } }` envelope for `prog_` ids (`Programmatic opportunities use batch generation, not individual briefs`), `decay_` ids (`Decay opportunities should use the update action`).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "error": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Either the API key is not linked to a user (`API key must be linked to a user to create briefs`, plain `{ \"data\": { \"error\": \"...\" } }` envelope), or the key lacks the `write:opportunities` scope, or the organization's subscription is inactive - canceled, paused, past due beyond grace, or an expired trial (structured Error, code `subscription_inactive`).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "error": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The opportunity exists but cannot be accepted: it is dismissed, already published, already covered by content on the site, already carries a brief, or another accept is holding it (claims older than 10 minutes are treated as abandoned and self-heal). Structured Error with code `opportunity_closed`. 409 rather than 404 because the row is still fetchable - it is the STATE that makes the request invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The opportunity's topic matches one of the organization's never-write-about terms, so no brief is minted and no quota is consumed. Plain `{ \"data\": { \"error\": \"...\" } }` envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "The organization's monthly brief allowance is exhausted (structured Error, code `brief_limit_exceeded`), or the shared API tier/budget limit denied the request. `Retry-After` on the brief-limit denial carries the seconds until the calendar-month counting window rolls, so it can be minutes or weeks - retrying sooner cannot succeed. The opportunity row is left untouched (the quota gate runs before the claim), so the same call can be replayed after the reset.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds until the monthly brief window resets. Omitted when the reset instant is unknown or already past."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Brief creation failed (`Failed to create brief from opportunity`). Any claim taken on the row is released first, so the opportunity is not left wedged at `in_progress`. Plain `{ \"data\": { \"error\": \"...\" } }` envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/answers/ask": {
      "post": {
        "operationId": "askAnswers",
        "summary": "Ask Frase Answers a question (SSE)",
        "description": "Developer-API equivalent of the Answers widget's ask endpoint: the same retrieval and generation pipeline, streamed back as Server-Sent Events. Requires the `answers:ask` scope.\n\nGates, in the order they run - each returns immediately:\n1. API key auth (401 bad/missing key, 403 missing scope, 429 tier budget).\n2. The `answers_v1` feature flag, resolved for the organization. Not enabled means 404 `Endpoint not found.` - the route is made to look nonexistent rather than admitting it exists.\n3. Body validation: the body must be JSON, `siteId` and `question` are required strings.\n4. `siteId` must belong to the authenticated organization and must not be trashed. A cross-org or deleted site returns the same 404 `Site not found.` as one that never existed.\n5. Per-site Answers entitlement, resolved against the target site's tier. An org admin who turned Answers off for the site gets 403 `site_feature_disabled`; a site whose Answers tier does not include developer-API access gets 403 `plan_required`. Trial-plan organizations skip this gate entirely.\n6. A widget must already be configured for the site. With none, 400 `site_not_configured` - set one up at /settings/answers first. When several non-revoked widgets exist the oldest is used; they share one knowledge base, and its branding flag drives the credit cap below.\n7. The question is sanitized (control characters stripped, whitespace normalized, 1-10,000 characters) and screened for prompt injection. Failures are 400 `invalid_param` or `disallowed_content`.\n8. A per-key Answers rate limit of 60 requests/minute, layered on top of the org-wide tier limit. Exceeding it is 429 `rate_limited` with `Retry-After` and `X-RateLimit-*` headers.\n\nBilling: Answers is metered per CONVERSATION, not per message. The first message of a new conversation reserves one Answers conversation credit; follow-ups that pass the returned `conversationId` back in are free ONLY while the conversation is still live: the row must match the same `visitorFingerprint` AND have been active within the last 120 minutes - an idle conversation is silently replaced by a NEW one, which charges another credit. When the cap is reached the just-created conversation is deleted (so it cannot linger as a 0-message row counting against the cap forever) and the call returns 429 with code `usage_limit_reached`, or `subscription_inactive` when the refusal came from the subscription rather than the cap.\n\nOmit `conversationId` to start a new conversation. `visitorFingerprint` is optional here (unlike the widget): it defaults to `api:<apiKeyId>`, a stable key-scoped identity, so multi-turn continuity works without minting visitor IDs. Once the stream opens the response is always HTTP 200 - failures inside generation arrive as an SSE `error` event followed by a `message-finish` event with `answerType: \"error\"`. Failures BEFORE the stream opens (credit reservation, conversation setup) surface as a plain 500 with no v1 envelope.",
        "tags": [
          "Answers"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "siteId",
                  "question"
                ],
                "properties": {
                  "siteId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. A site in your organization that has an Answers widget configured. Note this body field is camelCase, not snake_case."
                  },
                  "question": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 10000,
                    "description": "Required. The visitor question. Sanitized server-side and rejected if it trips prompt-injection detection."
                  },
                  "conversationId": {
                    "type": "string",
                    "description": "Optional. Continue an existing conversation (returned on the `conversation` SSE event of the first turn). Omit to start a new one - which is the turn that consumes a conversation credit."
                  },
                  "visitorFingerprint": {
                    "type": "string",
                    "description": "Optional. Identity used to resolve conversations. Defaults to `api:<apiKeyId>`, so each API key keeps its own thread per site."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SSE stream. Events are emitted as `event: <type>` / `data: <json>` pairs. Types, in order: `conversation` (once, first in the normal case - carries `conversationId`, `messageId` and the retrieved `sources`), zero or more `text-delta` (each carrying a `delta` string to append), an optional `error` when generation fails mid-stream, and `message-finish` (once, last). When generation fails before its first token the stream can consist of just `error` + `message-finish`, with no preceding `conversation` frame.",
            "headers": {
              "Content-Type": {
                "schema": {
                  "type": "string",
                  "example": "text/event-stream"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "example": "no-cache, no-transform"
                }
              },
              "Connection": {
                "schema": {
                  "type": "string",
                  "example": "keep-alive"
                }
              },
              "X-Accel-Buffering": {
                "schema": {
                  "type": "string",
                  "example": "no"
                },
                "description": "Disables proxy buffering so deltas arrive as they are produced."
              },
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Raw SSE frames. The `data` payload of each event type is:\n\n- `conversation`: `{ \"conversationId\": string, \"messageId\": string, \"sources\": [{ \"id\": integer, \"url\": string, \"title\": string, \"snippet\": string }] }`\n- `text-delta`: `{ \"delta\": string }`\n- `error`: `{ \"code\": string, \"message\": string }`\n- `message-finish`: `{ \"answerType\": \"rag\" | \"fallback_idk\" | \"error\", \"latencyMs\": integer, \"inputTokens\": integer, \"outputTokens\": integer, \"citations\": [{ \"position\": integer, \"url\": string, \"title\": string, \"snippet\": string }], \"rephraseSuggestions\"?: string[] }`\n\n`rephraseSuggestions` appears only when `answerType` is `fallback_idk` and the rephrase generator returned results. The widget-only `productCta` field is never emitted on this route, which does not pass a CTA configuration into generation. Note SSE payload keys are camelCase - they are the widget's wire format, reused verbatim."
                },
                "example": "event: conversation\ndata: {\"conversationId\":\"c1f0...\",\"messageId\":\"m9a2...\",\"sources\":[{\"id\":1,\"url\":\"https://example.com/pricing\",\"title\":\"Pricing\",\"snippet\":\"Plans start at...\"}]}\n\nevent: text-delta\ndata: {\"delta\":\"Plans start\"}\n\nevent: message-finish\ndata: {\"answerType\":\"rag\",\"latencyMs\":1840,\"inputTokens\":2103,\"outputTokens\":142,\"citations\":[{\"position\":1,\"url\":\"https://example.com/pricing\",\"title\":\"Pricing\",\"snippet\":\"Plans start at...\"}]}\n\n"
              }
            }
          },
          "400": {
            "description": "Body was not JSON (`invalid_request`), `siteId` or `question` missing (`invalid_param`), the question failed sanitization (`invalid_param`, e.g. too long - max 10,000 characters), the question tripped prompt-injection detection (`disallowed_content`), or the site has no widget configured (`site_not_configured`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The key lacks the `answers:ask` scope, Answers is disabled for this site by an organization admin (`site_feature_disabled`), or the site's Answers tier does not include developer-API access (`plan_required`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Answers is not enabled for this organization (`not_found`, `Endpoint not found.`) or the site does not exist, is trashed, or belongs to another organization (`not_found`, `Site not found.`, `param: \"siteId\"`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Per-key Answers rate limit exceeded - 60 requests per minute (`rate_limited`) - or the organization's Answers conversation cap for the billing period is reached (`usage_limit_reached`), or its subscription is inactive (`subscription_inactive`). On a conversation-cap refusal the conversation that was just created is deleted, so nothing is charged and nothing lingers.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds until the per-key window resets. Sent on the rate-limit denial only."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Rate-limit branch only; the credit-cap and subscription denials set no headers."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Rate-limit branch only; the credit-cap and subscription denials set no headers."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Epoch milliseconds at which the window resets. Rate-limit branch only; the credit-cap and subscription denials set no headers."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "A failure BEFORE the SSE stream opened (credit reservation, conversation setup). No v1 envelope - a plain framework error body. Any conversation created by this request is deleted on a pre-stream failure (credit reservation, message write, brand-context resolution), and an overage reservation the credit check committed is released — so nothing is charged. A follow-up's pre-existing conversation is never touched. No API-usage log row is written for this failure."
          }
        }
      }
    },
    "/audit/mcp-tool": {
      "post": {
        "operationId": "recordMcpToolInvocation",
        "summary": "Record an MCP tool invocation",
        "description": "Append-only telemetry ingest for MCP tool calls. The Frase MCP server (npm/stdio build) posts one row here per tool invocation; the in-app HTTP MCP surface writes the same row directly without the round trip. Rows land in `mcp_tool_invocations`, scoped to the authenticated organization, and are swept by the daily retention job.\n\nNo scope is required beyond a valid API key - any key for the organization may write its own telemetry. Only a hash and the size of the tool input are stored, never the input itself, so no customer content reaches this table.\n\nA dedicated per-key rate limit of 100 requests/minute sits on top of the shared tier bucket (keyed on organization plus user, falling back to the key id), so one buggy client cannot drive unbounded row growth between retention sweeps.\n\nClients should treat this call as fire-and-forget: telemetry must never break a tool call. Every field except `error_code` is required, and unknown fields are ignored.",
        "tags": [
          "Audit"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tool_name",
                  "input_hash",
                  "input_size",
                  "result_status",
                  "duration_ms"
                ],
                "properties": {
                  "tool_name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100,
                    "description": "Required. The MCP tool that ran. Trimmed before validation."
                  },
                  "input_hash": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$",
                    "description": "Required. SHA-256 of the JSON-serialized tool input, 64 hex characters. Case-insensitive on the way in; stored lowercased."
                  },
                  "input_size": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10000000,
                    "description": "Required. Byte length of the serialized input (UTF-8)."
                  },
                  "result_status": {
                    "type": "string",
                    "enum": [
                      "success",
                      "error",
                      "rate_limited",
                      "validation_error",
                      "not_found",
                      "unauthorized",
                      "timeout"
                    ],
                    "description": "Required. How the tool call ended."
                  },
                  "duration_ms": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 900000,
                    "description": "Required. Wall-clock duration of the tool call, capped at 15 minutes."
                  },
                  "error_code": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 50,
                    "pattern": "^[a-z0-9_\\-.]+$",
                    "description": "Optional. Short machine code for a non-success result. Trimmed; letters, digits, underscore, hyphen and dot only (case-insensitive). Stored as null when omitted."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Invocation recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "recorded": {
                          "type": "boolean",
                          "description": "Always true on 201."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The body was not a JSON object, or a field failed validation. Structured Error with code `invalid_param`; `param` names the first failing field (or `body`) and `message` carries that field's validation message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "The per-key ingest limit of 100 requests/minute was exceeded, or the shared API tier/budget limit denied the request. The ingest denial uses the plain `{ \"data\": { \"error\": \"Rate limit exceeded. Retry after N seconds.\" } }` envelope and carries no Retry-After header - the retry delay is in the message.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "error": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "The insert failed (`Failed to record MCP audit event`). Plain `{ \"data\": { \"error\": \"...\" } }` envelope. Clients must not retry in a way that blocks the tool call this row describes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/site-health/cannibalization": {
      "get": {
        "operationId": "getSiteHealthCannibalization",
        "summary": "Get keyword cannibalization conflicts",
        "description": "Keyword-cannibalization conflict groups recorded by the audit pipeline: one entry per keyword that more than one page competes for. Requires the `read:site-health` scope. Pass either `audit_id` (a specific completed audit) or `site_id` (resolves that site's most recent completed audit, ordered by created_at, and reports on it). If both are sent, `audit_id` wins and `site_id` is ignored; if neither is sent you get a 400 on `audit_id`. BOTH modes return the SAME payload: a plain ARRAY of conflict groups directly under `data` (not an object, and not the internal link graph an older build returned here). The array is empty when the audit ran but stored no conflicts. Read-only: no side effects beyond API-usage logging. OPTIONS is supported for CORS preflight (204, `Access-Control-Allow-Methods: GET, OPTIONS`). Note the two 404 bodies on this route are data-wrapped (`{\"data\":{\"error\":\"...\"}}`), not the Stripe-style error envelope used by 400/401/403/429.",
        "tags": [
          "Site Health"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "audit_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "A completed audit to report on. Required unless `site_id` is given. Must be a UUID and must belong to your organization."
          },
          {
            "name": "site_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Report on this site's latest COMPLETED audit. Ignored when `audit_id` is present. Must be a UUID."
          }
        ],
        "responses": {
          "200": {
            "description": "Keyword-cannibalization conflict groups for the resolved audit. Empty array when the audit stored none.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "keyword": {
                            "type": "string",
                            "description": "The keyword the pages are competing for."
                          },
                          "severity": {
                            "type": "string",
                            "enum": [
                              "low",
                              "medium",
                              "critical",
                              "unknown"
                            ],
                            "description": "The group's stored severity level. \"unknown\" when the persisted group carried no severity string (older audit rows), never a fabricated level."
                          },
                          "pages": {
                            "type": "array",
                            "description": "The competing pages. Entries without a URL are dropped.",
                            "items": {
                              "type": "object",
                              "properties": {
                                "url": {
                                  "type": "string"
                                },
                                "title": {
                                  "type": "string",
                                  "description": "Empty string when the crawl recorded no title — always a string, never null."
                                },
                                "similarity": {
                                  "type": "number",
                                  "nullable": true,
                                  "description": "Content similarity to the other pages in the group. Null when the stored group carried no numeric similarity."
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Data-wrapped, NOT the standard error envelope. Two cases: `site_id` mode where the site has no completed audit (\"No completed audit found for this site. Run an audit first.\"), and an `audit_id` (or resolved audit) your organization does not own / that does not exist (\"Audit not found\").",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "enum": [
                            "No completed audit found for this site. Run an audit first.",
                            "Audit not found"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected failure while reading the audit. Data-wrapped, with a fixed message (`Failed to get cannibalization data`) — v1 routes never leak the underlying error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "example": "Failed to get cannibalization data"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/site-health/issues": {
      "get": {
        "operationId": "getSiteHealthIssues",
        "summary": "List aggregated site health issues",
        "description": "Every issue found on a site's most recent audit, aggregated across pages: one entry per issue title with the pages it affects, plus keyword-cannibalization groups folded in as issues of their own. Requires the `read:site-health` scope. Issues whose title was marked fixed in the audit's metadata are excluded, and the list is sorted by severity (critical, high, medium, low). `summary` is recounted over the returned (deduplicated, filtered) issues, so it will not always match `audit_stats`, which reports the raw audit run. `total_occurrences` counts per-page occurrences rather than deduplicated issues, so it is normally larger than `summary.total`. Read-only: no side effects beyond API-usage logging. OPTIONS is supported for CORS preflight (204, `Access-Control-Allow-Methods: GET, OPTIONS`). Note the 404 and 500 bodies are data-wrapped (`{\"data\":{\"error\":\"...\"}}`), not the Stripe-style error envelope used by 400/401/403/429.",
        "tags": [
          "Site Health"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Required. The site to report on; must be a UUID and must be owned by your organization (a deleted site reads as not found)."
          }
        ],
        "responses": {
          "200": {
            "description": "Aggregated issues for the site",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "issues": {
                          "type": "array",
                          "description": "Sorted critical first. Empty when the site has no unfixed issues (including a site that has never been audited).",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The underlying audit issue's id for standard issues; `cannibalization-<groupId>` for cannibalization issues. Stable only within a single audit run."
                              },
                              "title": {
                                "type": "string",
                                "description": "The aggregation key — issues sharing a title across pages are merged into one entry."
                              },
                              "description": {
                                "type": "string",
                                "description": "Page-specific counts are stripped once a group spans more than one page, so the text never claims one page's figures for the whole group."
                              },
                              "severity": {
                                "type": "string",
                                "enum": [
                                  "critical",
                                  "high",
                                  "medium",
                                  "low"
                                ]
                              },
                              "category": {
                                "type": "string",
                                "enum": [
                                  "technical",
                                  "content",
                                  "aeo",
                                  "cannibalization",
                                  "agent_readiness"
                                ]
                              },
                              "issue_type": {
                                "type": "string",
                                "enum": [
                                  "standard",
                                  "cannibalization"
                                ],
                                "description": "Defaults to \"standard\" when the underlying issue carried no type."
                              },
                              "pages_affected": {
                                "type": "integer",
                                "description": "Number of distinct pages in `page_refs`."
                              },
                              "page_refs": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "page_id": {
                                      "type": "string"
                                    },
                                    "page_title": {
                                      "type": "string",
                                      "description": "Falls back to the page URL for cannibalization entries that have no title."
                                    },
                                    "page_url": {
                                      "type": "string"
                                    },
                                    "target_keyword": {
                                      "type": "string",
                                      "nullable": true,
                                      "description": "Cannibalization issues only; always null on standard issues."
                                    },
                                    "similarity": {
                                      "type": "number",
                                      "nullable": true,
                                      "description": "Cannibalization issues only; always null on standard issues."
                                    },
                                    "word_count": {
                                      "type": "integer",
                                      "nullable": true,
                                      "description": "Cannibalization issues only; always null on standard issues."
                                    },
                                    "internal_links": {
                                      "type": "integer",
                                      "nullable": true,
                                      "description": "Cannibalization issues only; always null on standard issues."
                                    }
                                  }
                                }
                              },
                              "fix_suggestion": {
                                "type": "string",
                                "nullable": true,
                                "description": "For cannibalization issues this is the recommendation's message. Null when the issue carries no suggestion."
                              },
                              "keyword": {
                                "type": "string",
                                "nullable": true,
                                "description": "The cannibalized keyword. Null on standard issues."
                              },
                              "recommendation": {
                                "type": "object",
                                "nullable": true,
                                "description": "Present on cannibalization issues; null on standard issues.",
                                "properties": {
                                  "type": {
                                    "type": "string",
                                    "enum": [
                                      "merge",
                                      "differentiate",
                                      "consolidate",
                                      "re-optimize"
                                    ]
                                  },
                                  "message": {
                                    "type": "string"
                                  },
                                  "primary_page_url": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "The page the recommendation would keep as primary, when it names one."
                                  },
                                  "actions": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    },
                                    "description": "Ordered, human-readable steps."
                                  }
                                }
                              }
                            }
                          }
                        },
                        "summary": {
                          "type": "object",
                          "description": "Counts recomputed over the returned issues (deduplicated, fixed-issues removed). Keys are single words and are NOT snake_cased.",
                          "properties": {
                            "critical": {
                              "type": "integer"
                            },
                            "high": {
                              "type": "integer"
                            },
                            "medium": {
                              "type": "integer"
                            },
                            "low": {
                              "type": "integer"
                            },
                            "total": {
                              "type": "integer"
                            }
                          }
                        },
                        "total_occurrences": {
                          "type": "integer",
                          "description": "Raw occurrence count: the audit's own issue total plus every page in every cannibalization group. Counts occurrences, not deduplicated issues, and is not filtered by the fixed-issues list — so it is normally larger than `summary.total`."
                        },
                        "audit_summary": {
                          "type": "string",
                          "nullable": true,
                          "description": "The latest completed audit's stored summary text. Null when no crawl has completed or the run produced none."
                        },
                        "audit_stats": {
                          "type": "object",
                          "nullable": true,
                          "description": "Figures from the latest completed audit run. Null when the site has no completed audit. Only these four fields are exposed here (the site-health overview publishes more).",
                          "properties": {
                            "overall_score": {
                              "type": "integer",
                              "nullable": true
                            },
                            "pages_audited": {
                              "type": "integer",
                              "nullable": true
                            },
                            "critical_issues": {
                              "type": "integer",
                              "nullable": true
                            },
                            "total_issues": {
                              "type": "integer",
                              "nullable": true
                            }
                          }
                        },
                        "has_gsc": {
                          "type": "boolean",
                          "description": "Whether Google Search Console data backed this site's analysis. False when unknown."
                        },
                        "last_audit_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true,
                          "description": "The audit these issues were drawn from. Null when the site has no completed audit."
                        },
                        "site_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true,
                          "description": "Echoes the requested site."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Site not found — unknown id, deleted, or owned by another organization. Data-wrapped, NOT the standard error envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "example": "Site not found"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The issues could not be assembled. Data-wrapped, with a fixed message (`Failed to list site health issues`) — v1 routes never leak the underlying error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "example": "Failed to list site health issues"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/sites/{siteId}/cms-token": {
      "get": {
        "operationId": "getSiteCmsDeliveryToken",
        "summary": "Get a site's FraseCMS delivery token",
        "description": "Returns the site's CURRENT headless delivery token — the bearer credential the public FraseCMS read endpoints accept. Non-mutating: the token is rebuilt (HMAC) from the site's stored secret and version, so repeated calls return the SAME token. It is therefore NOT a show-once secret: as long as the site's secret exists you can fetch the live token again here. Only rotation (POST /sites/{siteId}/cms-token/rotate) changes it, and only revocation removes it. If the token has been revoked (the site's secret was nulled), this returns 200 with `{ \"revoked\": true }` and nothing else — the endpoint NEVER re-mints a revoked token; re-issue explicitly by rotating. Gates: requires the `write:sites` scope even though the verb is GET, because the response reveals a live credential — a read-only key is refused with 403. Responses carry `Cache-Control: no-store`; never cache or log the token. An org-scoped bucket allows 60 calls per minute per organization on top of your API key's own limits; exceeding it returns a data-wrapped 429 carrying no Retry-After header. Token format is `fcms_<base64url(siteId:version:hmac)>`; `api_endpoint` is the ready-to-call posts URL that embeds it. OPTIONS is supported for CORS preflight (204, `Access-Control-Allow-Methods: GET, OPTIONS`).",
        "tags": [
          "Sites"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "siteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Site ID. Must be a UUID and must be owned by your organization."
          }
        ],
        "responses": {
          "200": {
            "description": "The live delivery token, or the revoked marker. Sent with `Cache-Control: no-store`.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                },
                "description": "Always `no-store` — the body carries a live credential and must not be cached by a browser, CDN, or proxy."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "oneOf": [
                        {
                          "type": "object",
                          "title": "Active token",
                          "properties": {
                            "token": {
                              "type": "string",
                              "description": "The delivery token, `fcms_` + base64url of `siteId:version:hmac`. Re-derivable: fetching again returns the same string until a rotate or revoke.",
                              "example": "fcms_ZXhhbXBsZTox..."
                            },
                            "version": {
                              "type": "integer",
                              "description": "The site's current delivery-token version. Incremented by every rotation; tokens carrying an older version stop verifying."
                            },
                            "api_endpoint": {
                              "type": "string",
                              "description": "Ready-to-call posts endpoint with the token embedded: `<app base URL>/api/cms/<token>/posts`."
                            },
                            "revoked": {
                              "type": "boolean",
                              "enum": [
                                false
                              ]
                            }
                          }
                        },
                        {
                          "type": "object",
                          "title": "Revoked",
                          "description": "Terminal state: the site's secret was nulled. No token, version, or endpoint is returned and this endpoint will not re-mint one — rotate to re-issue.",
                          "properties": {
                            "revoked": {
                              "type": "boolean",
                              "enum": [
                                true
                              ]
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "FraseCMS is not enabled for this site (`cms_disabled`). Enable the FraseCMS connection first; nothing is minted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "type": "validation_error",
                    "code": "cms_disabled",
                    "message": "CMS not enabled for this site",
                    "doc_url": "https://docs.frase.io/api/errors#cms_disabled"
                  },
                  "request_id": "req_abc123"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Two shapes: the standard API-key limit (Stripe-style error envelope, with Retry-After), or this endpoint's org-scoped mint bucket of 60/minute, which is data-wrapped and carries NO Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "error": {
                              "type": "string",
                              "example": "Rate limit exceeded. Try again later."
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "The token could not be read. Data-wrapped, with a fixed message (`Failed to get delivery token`) — v1 routes never leak the underlying error. Nothing was changed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "example": "Failed to get delivery token"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/sites/{siteId}/cms-token/rotate": {
      "post": {
        "operationId": "rotateSiteCmsDeliveryToken",
        "summary": "Rotate a site's FraseCMS delivery token",
        "description": "Mints a brand-new headless delivery token for the site and returns it. Destructive and IRREVERSIBLE: a fresh random per-site secret is generated and the site's delivery-token version is incremented in a single update, so EVERY previously issued token for this site stops verifying the moment this call succeeds. There is no un-rotate — update every consumer with the returned token. The new token itself is not lost if you miss the response: while it is live you can read the same string back from GET /sites/{siteId}/cms-token (it is re-derived from the stored secret). What is gone forever is the old token. Gates: requires the `write:content` scope (note the sibling GET requires `write:sites` instead). Takes no request body — anything sent is ignored. An org-scoped bucket allows 10 rotations per hour per organization; exceeding it returns a data-wrapped 429 with no Retry-After header. Unlike the GET, this response does NOT set Cache-Control: no-store even though it carries a live credential — do not cache or log it. Success is recorded in analytics as a rotation for the site. OPTIONS is supported for CORS preflight (204, `Access-Control-Allow-Methods: POST, OPTIONS`).",
        "tags": [
          "Sites"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "siteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Site ID. Must be a UUID and must be owned by your organization."
          }
        ],
        "responses": {
          "200": {
            "description": "Rotated. The old token is already invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "token": {
                          "type": "string",
                          "description": "The new delivery token, `fcms_` + base64url of `siteId:version:hmac`. Use it as the path credential on the FraseCMS read endpoints (`/api/cms/<token>/posts`); the rotate response does not build that URL for you — GET /sites/{siteId}/cms-token returns it as `api_endpoint`.",
                          "example": "fcms_ZXhhbXBsZToy..."
                        },
                        "version": {
                          "type": "integer",
                          "description": "The site's new delivery-token version, one higher than before. Tokens carrying any earlier version no longer verify."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The site is in Trash (`site_deleted`). Terminal and client-actionable — restore the site before rotating; retrying will not clear it. Data-wrapped, and unusually carries a machine-readable `code` alongside the message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "example": "This site has been deleted. Restore it from Trash to keep configuring it."
                        },
                        "code": {
                          "type": "string",
                          "enum": [
                            "site_deleted"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Two shapes: the standard API-key limit (Stripe-style error envelope, with Retry-After), or this endpoint's org-scoped rotation bucket of 10/hour, which is data-wrapped and carries NO Retry-After. A refused rotation changes nothing.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "error": {
                              "type": "string",
                              "example": "Rate limit exceeded. Try again later."
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "The rotation failed. Data-wrapped, with a fixed message (`Failed to rotate delivery token`) — v1 routes never leak the underlying error. Re-read the token with GET /sites/{siteId}/cms-token to confirm which version is live before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "example": "Failed to rotate delivery token"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/briefs/{id}/regenerate": {
      "post": {
        "operationId": "regenerateBrief",
        "summary": "Rebuild a brief from its research session's current research",
        "description": "When research changed after the brief was generated (POST /briefs reports `research_updated_since_generation: true`), this re-flattens the session's live keywords/evidence into a fresh content plan and repopulates the brief. Work-preserving: a brief locked by a generated article or hand edits is never overwritten — the refresh lands in a forked brief (`forked: true`, billing-exempt the first time a brief is superseded) and the original stays. A current plan is never re-run (`already_current: true`). Poll the returned `brief_id`.",
        "tags": [
          "Briefs"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Already current — nothing regenerated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "brief_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "regenerated": {
                          "type": "boolean"
                        },
                        "already_current": {
                          "type": "boolean"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Regeneration started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "brief_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "The brief being (re)built — a NEW id when forked."
                        },
                        "regenerating": {
                          "type": "boolean"
                        },
                        "forked": {
                          "type": "boolean",
                          "description": "true when the original brief was locked by an article/hand edits and the refresh went into a fresh brief."
                        },
                        "supersedes_brief_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Present when forked: the brief this refresh replaces as the session's live brief (the original stays untouched). Session handoff only — a repeat, metered supersession writes no billing-lineage marker."
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Two conflicts share this code — read the error text: (a) a generation is already in progress for this session; (b) the named brief was superseded by an earlier fork and is no longer the session's live brief — the response then carries `live_brief_id`; retry against that id.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        },
                        "live_brief_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Present only on the superseded-brief conflict: the session's current live brief."
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "id is not a valid UUID"
          },
          "500": {
            "description": "The regeneration could not be started; the current brief is unchanged"
          },
          "422": {
            "description": "Not created from research, or no completed brief yet"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/content/{id}/evaluate-rules": {
      "post": {
        "operationId": "evaluateContentRules",
        "summary": "Evaluate every enabled rule set against a content row",
        "description": "Run every enabled rule set (org-wide plus the content's site) against an existing Frase content row, mirroring the in-app governance agent. Unlike the stateless `POST /rules/evaluate`, this endpoint persists the outcome by default so the content's governance status stays current; pass `save_results: false` to evaluate without writing.",
        "tags": [
          "Rules"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Content ID to evaluate",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional. Scopes site-scoped rule sets and score computation."
                  },
                  "save_results": {
                    "type": "boolean",
                    "description": "Persist the evaluation to the content's governance status. Defaults to true; pass false for a preview."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Evaluation result across every applied rule set",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "content_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "overall_status": {
                          "type": "string",
                          "enum": [
                            "pass",
                            "warning",
                            "fail"
                          ]
                        },
                        "rule_set_results": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "rule_set_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "rule_set_name": {
                                "type": "string"
                              },
                              "overall_status": {
                                "type": "string",
                                "enum": [
                                  "pass",
                                  "warning",
                                  "fail"
                                ]
                              },
                              "summary": {
                                "nullable": true
                              },
                              "results": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "rule_id": {
                                      "type": "string",
                                      "format": "uuid"
                                    },
                                    "rule_name": {
                                      "type": "string"
                                    },
                                    "condition_type": {
                                      "type": "string"
                                    },
                                    "severity": {
                                      "type": "string",
                                      "enum": [
                                        "error",
                                        "warning",
                                        "info"
                                      ]
                                    },
                                    "passed": {
                                      "type": "boolean"
                                    },
                                    "skipped": {
                                      "type": "boolean",
                                      "description": "The rule could not run (e.g. a score_threshold rule with no target keywords). A skipped rule is neither a pass nor a failure - never read it as a genuine pass."
                                    },
                                    "value": {
                                      "nullable": true
                                    },
                                    "threshold": {
                                      "nullable": true
                                    },
                                    "message": {
                                      "type": "string",
                                      "nullable": true
                                    },
                                    "fix_hint": {
                                      "type": "string",
                                      "nullable": true
                                    }
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/rule-sets/{id}/evaluate": {
      "post": {
        "operationId": "evaluateRuleSetAgainstContent",
        "summary": "Evaluate one rule set against a content row",
        "description": "Run a single rule set against an existing Frase content row. The outcome is persisted by default (pass `save_results: false` to preview without writing). Use `POST /content/{id}/evaluate-rules` to run every applicable rule set at once.",
        "tags": [
          "Rule Sets"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Rule set ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "content_id"
                ],
                "properties": {
                  "content_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The content row to evaluate."
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional. Scopes site-scoped rules and score computation."
                  },
                  "save_results": {
                    "type": "boolean",
                    "description": "Persist the evaluation. Defaults to true; pass false for a preview."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Evaluation result for the rule set",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "rule_set_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "rule_set_name": {
                          "type": "string"
                        },
                        "content_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "overall_status": {
                          "type": "string",
                          "enum": [
                            "pass",
                            "warning",
                            "fail"
                          ]
                        },
                        "summary": {
                          "nullable": true
                        },
                        "results": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "rule_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "rule_name": {
                                "type": "string"
                              },
                              "condition_type": {
                                "type": "string"
                              },
                              "severity": {
                                "type": "string",
                                "enum": [
                                  "error",
                                  "warning",
                                  "info"
                                ]
                              },
                              "passed": {
                                "type": "boolean"
                              },
                              "skipped": {
                                "type": "boolean",
                                "description": "The rule could not run (e.g. a score_threshold rule with no target keywords). A skipped rule is neither a pass nor a failure - never read it as a genuine pass."
                              },
                              "value": {
                                "nullable": true
                              },
                              "threshold": {
                                "nullable": true
                              },
                              "message": {
                                "type": "string",
                                "nullable": true
                              },
                              "fix_hint": {
                                "type": "string",
                                "nullable": true
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/rule-sets/{id}/rules": {
      "post": {
        "operationId": "addRuleToRuleSet",
        "summary": "Add a rule to a rule set",
        "description": "Attach an existing rule to a rule set at an optional sort position. System rule sets cannot be modified.",
        "tags": [
          "Rule Sets"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Rule set ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "rule_id"
                ],
                "properties": {
                  "rule_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The rule to attach."
                  },
                  "sort_order": {
                    "type": "integer",
                    "description": "Optional position of the rule within the set."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Rule attached to the set",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "The rule-set-to-rule link ID."
                        },
                        "rule_set_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "rule_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "sort_order": {
                          "type": "integer",
                          "nullable": true
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "System rule set cannot be modified",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The rule is already attached to this set",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      },
      "delete": {
        "operationId": "removeRuleFromRuleSet",
        "summary": "Remove a rule from a rule set",
        "description": "Detach a rule from a rule set. The rule itself is not deleted. System rule sets cannot be modified.",
        "tags": [
          "Rule Sets"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Rule set ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "rule_id",
            "in": "query",
            "required": true,
            "description": "The rule to detach from the set",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Rule detached from the set",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "removed": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "System rule set cannot be modified",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/clusters": {
      "get": {
        "operationId": "listClusters",
        "summary": "List topic clusters",
        "description": "Retrieve the organization's topic clusters, optionally scoped to a site.",
        "tags": [
          "Clusters"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "required": false,
            "description": "Filter to a single site (org-wide clusters are always included)",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of clusters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string",
                            "nullable": true
                          },
                          "color": {
                            "type": "string",
                            "nullable": true
                          },
                          "pillar_content_id": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true
                          },
                          "pillar_title": {
                            "type": "string",
                            "nullable": true
                          },
                          "site_id": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true,
                            "description": "The site this cluster is scoped to, or null for an org-wide cluster."
                          },
                          "seed_keywords": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "nullable": true
                          },
                          "content_count": {
                            "type": "integer"
                          },
                          "brief_count": {
                            "type": "integer"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updated_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      },
      "post": {
        "operationId": "createCluster",
        "summary": "Create a topic cluster",
        "description": "Create a topic cluster. Omit `site_id` for an org-wide cluster, or pass a site your organization owns to scope it. A `site_id` the org does not own returns 404.",
        "tags": [
          "Clusters"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Required. Cluster name."
                  },
                  "description": {
                    "type": "string",
                    "description": "Optional summary of the cluster's topic."
                  },
                  "color": {
                    "type": "string",
                    "description": "Optional display color."
                  },
                  "seed_keywords": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Optional seed keywords for the cluster."
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional. Scope the cluster to a site the org owns; omit for an org-wide cluster."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Cluster created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string",
                          "nullable": true
                        },
                        "color": {
                          "type": "string",
                          "nullable": true
                        },
                        "site_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true,
                          "description": "Echoes the scope just written; null for an org-wide cluster."
                        },
                        "seed_keywords": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "nullable": true
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/clusters/suggest": {
      "post": {
        "operationId": "suggestClusters",
        "summary": "Suggest new topic clusters for a site",
        "description": "Propose new topic clusters for a site, reasoning from the org's existing cluster taxonomy plus unclustered brief topics and content titles as demand signals. Returns an empty array when the site has no signals to reason from.",
        "tags": [
          "Clusters"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The site to suggest clusters for."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ranked cluster suggestions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string",
                            "description": "Proposed cluster name."
                          },
                          "pillar_topic": {
                            "type": "string",
                            "description": "The pillar topic the cluster would be built around."
                          },
                          "suggested_content": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Suggested supporting article topics."
                          },
                          "confidence": {
                            "type": "number",
                            "description": "Model confidence in the suggestion, 0-1."
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/clusters/{id}": {
      "get": {
        "operationId": "getCluster",
        "summary": "Get a topic cluster",
        "description": "Retrieve a single cluster with its assigned content and briefs.",
        "tags": [
          "Clusters"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Cluster ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cluster detail",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string",
                          "nullable": true
                        },
                        "color": {
                          "type": "string",
                          "nullable": true
                        },
                        "pillar_content_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true
                        },
                        "site_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true,
                          "description": "The site this cluster is scoped to, or null for an org-wide cluster."
                        },
                        "seed_keywords": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "nullable": true
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "content": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "title": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "word_count": {
                                "type": "integer",
                                "nullable": true
                              },
                              "is_pillar": {
                                "type": "boolean"
                              },
                              "updated_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          }
                        },
                        "briefs": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "topic": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/clusters/{id}/assign": {
      "post": {
        "operationId": "assignToCluster",
        "summary": "Assign content or a brief to a cluster",
        "description": "Assign one or more content rows and/or briefs to a cluster. At least one of `content_id` or `brief_id` is required.",
        "tags": [
          "Clusters"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Cluster ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Content to assign. At least one of content_id or brief_id is required."
                  },
                  "brief_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Brief to assign. At least one of content_id or brief_id is required."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Items assigned to the cluster",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "cluster_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "assigned": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": [
                                  "content",
                                  "brief"
                                ]
                              },
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/clusters/{id}/pillar": {
      "post": {
        "operationId": "setClusterPillar",
        "summary": "Elect a cluster's pillar content",
        "description": "Promote a content row to be the cluster's pillar. The content must already be a member of the cluster (`not_a_member` otherwise) and must be an article, not a brief (`brief_not_allowed`). Electing a new pillar displaces the previous one, returned as `displaced_content_id`.",
        "tags": [
          "Clusters"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Cluster ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "content_id"
                ],
                "properties": {
                  "content_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The cluster member to elect as pillar."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Pillar elected",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "cluster_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "pillar_content_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "pillar_title": {
                          "type": "string",
                          "nullable": true
                        },
                        "displaced_content_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true,
                          "description": "The content that was pillar before this call, or null if there was none."
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The content is not a cluster member (not_a_member) or is a brief (brief_not_allowed)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/playbooks/{id}/runs": {
      "get": {
        "operationId": "listPlaybookRuns",
        "summary": "List a playbook's runs",
        "description": "Retrieve runs for a playbook, most recent first.",
        "tags": [
          "Playbooks"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Playbook ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of playbook runs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "playbook_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "running",
                              "paused",
                              "completed",
                              "failed",
                              "cancelled"
                            ]
                          },
                          "topic": {
                            "type": "string",
                            "nullable": true
                          },
                          "current_step_index": {
                            "type": "integer",
                            "nullable": true
                          },
                          "current_step_name": {
                            "type": "string",
                            "nullable": true,
                            "description": "The name this run stored for the current step position, resilient to later edits of the playbook definition."
                          },
                          "started_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "completed_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "paused_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "error": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      },
      "post": {
        "operationId": "startPlaybookRun",
        "summary": "Start a playbook run",
        "description": "Kick off a run of a playbook. Depending on the playbook's first step you may pass a `topic` (to generate from), an existing `content_id` (to operate on), and/or a `site_id`. A disabled playbook, an exhausted run quota, or too many concurrent runs are surfaced with specific error codes.",
        "tags": [
          "Playbooks"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Playbook ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "topic": {
                    "type": "string",
                    "description": "Topic to seed the run, when the playbook generates new content."
                  },
                  "content_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Existing content the run should operate on."
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Site the run is scoped to, when required by the playbook."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Run started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "playbook_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "running",
                            "paused",
                            "completed",
                            "failed",
                            "cancelled"
                          ]
                        },
                        "topic": {
                          "type": "string",
                          "nullable": true
                        },
                        "current_step_index": {
                          "type": "integer",
                          "nullable": true
                        },
                        "current_step_name": {
                          "type": "string",
                          "nullable": true,
                          "description": "The name this run stored for the current step position, resilient to later edits of the playbook definition."
                        },
                        "started_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "completed_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true,
                          "description": "Always null at start; populated when the run reaches a terminal state."
                        },
                        "paused_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true,
                          "description": "Always null at start; populated only when the run pauses."
                        },
                        "error": {
                          "type": "string",
                          "nullable": true,
                          "description": "Always null at start; populated only on failure."
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Your subscription does not include this feature",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Playbook run limit reached, or too many concurrent runs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/playbooks/{id}/runs/{runId}": {
      "get": {
        "operationId": "getPlaybookRun",
        "summary": "Get a playbook run",
        "description": "Retrieve a single run with its per-step results and outputs.",
        "tags": [
          "Playbooks"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Playbook ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "runId",
            "in": "path",
            "required": true,
            "description": "Run ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Run detail",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "playbook_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "content_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "running",
                            "paused",
                            "completed",
                            "failed",
                            "cancelled"
                          ]
                        },
                        "topic": {
                          "type": "string",
                          "nullable": true
                        },
                        "current_step_index": {
                          "type": "integer",
                          "nullable": true
                        },
                        "current_step_name": {
                          "type": "string",
                          "nullable": true,
                          "description": "The name this run stored for the current step position."
                        },
                        "step_results": {
                          "type": "array",
                          "nullable": true,
                          "items": {
                            "type": "object"
                          },
                          "description": "Per-step results captured as the run progressed."
                        },
                        "outputs": {
                          "nullable": true,
                          "description": "The run's accumulated outputs."
                        },
                        "started_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "completed_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "paused_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "retry_count": {
                          "type": "integer",
                          "nullable": true
                        },
                        "error": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/playbooks/{id}/runs/{runId}/cancel": {
      "post": {
        "operationId": "cancelPlaybookRun",
        "summary": "Cancel a playbook run",
        "description": "Cancel a run that is still pending, running, or paused. A run that has already reached a terminal state, or finishes between the check and the write, returns 409 `invalid_state`.",
        "tags": [
          "Playbooks"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Playbook ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "runId",
            "in": "path",
            "required": true,
            "description": "Run ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Run cancelled",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "cancelled": {
                          "type": "boolean"
                        },
                        "run_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The run is no longer in a cancellable state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/playbooks/{id}/runs/{runId}/resume": {
      "post": {
        "operationId": "resumePlaybookRun",
        "summary": "Resume a paused playbook run",
        "description": "Provide human-review input to a run paused for review, resuming execution. Only paused runs are resumable; anything else returns 409 `invalid_state`.",
        "tags": [
          "Playbooks"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Playbook ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "runId",
            "in": "path",
            "required": true,
            "description": "Run ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "input"
                ],
                "properties": {
                  "input": {
                    "type": "string",
                    "description": "Required. The reviewer's input the paused step is waiting on."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Run resuming",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "resuming"
                          ]
                        },
                        "run_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The run is not in a resumable (paused) state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/authors": {
      "get": {
        "operationId": "listCmsAuthors",
        "summary": "List CMS authors",
        "description": "List the organization's FraseCMS authors.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of authors",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "authors": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "name": {
                                "type": "string"
                              },
                              "slug": {
                                "type": "string"
                              },
                              "bio": {
                                "type": "string",
                                "nullable": true
                              },
                              "avatar_url": {
                                "type": "string",
                                "nullable": true
                              },
                              "email": {
                                "type": "string",
                                "nullable": true
                              },
                              "role": {
                                "type": "string",
                                "nullable": true
                              },
                              "post_count": {
                                "type": "integer"
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      },
      "post": {
        "operationId": "createCmsAuthor",
        "summary": "Create a CMS author",
        "description": "Create a FraseCMS author byline for the organization.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Required. Display name."
                  },
                  "bio": {
                    "type": "string",
                    "nullable": true
                  },
                  "avatar_url": {
                    "type": "string",
                    "nullable": true
                  },
                  "email": {
                    "type": "string",
                    "nullable": true
                  },
                  "role": {
                    "type": "string",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Author created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "author": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "name": {
                              "type": "string"
                            },
                            "slug": {
                              "type": "string"
                            },
                            "bio": {
                              "type": "string",
                              "nullable": true
                            },
                            "avatar_url": {
                              "type": "string",
                              "nullable": true
                            },
                            "email": {
                              "type": "string",
                              "nullable": true
                            },
                            "role": {
                              "type": "string",
                              "nullable": true
                            },
                            "post_count": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/authors/{id}": {
      "patch": {
        "operationId": "updateCmsAuthor",
        "summary": "Update a CMS author",
        "description": "Update a FraseCMS author. Every field is optional; omitted fields are left unchanged.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Author ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "bio": {
                    "type": "string",
                    "nullable": true
                  },
                  "avatar_url": {
                    "type": "string",
                    "nullable": true
                  },
                  "email": {
                    "type": "string",
                    "nullable": true
                  },
                  "role": {
                    "type": "string",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Author updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "author": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "name": {
                              "type": "string"
                            },
                            "slug": {
                              "type": "string"
                            },
                            "bio": {
                              "type": "string",
                              "nullable": true
                            },
                            "avatar_url": {
                              "type": "string",
                              "nullable": true
                            },
                            "email": {
                              "type": "string",
                              "nullable": true
                            },
                            "role": {
                              "type": "string",
                              "nullable": true
                            },
                            "post_count": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      },
      "delete": {
        "operationId": "deleteCmsAuthor",
        "summary": "Delete a CMS author",
        "description": "Delete a FraseCMS author. The byline is unlinked from its posts and co-author rows are cascaded.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Author ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Author deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "string",
                          "format": "uuid",
                          "description": "ID of the deleted author."
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/authors/{id}/merge": {
      "post": {
        "operationId": "mergeCmsAuthors",
        "summary": "Merge two CMS authors",
        "description": "Re-point the byline and co-author rows from this author onto `merge_into`, then delete this author. Runs as one transaction.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Author ID to merge and delete",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "merge_into"
                ],
                "properties": {
                  "merge_into": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The author that absorbs this one's posts."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authors merged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "merged": {
                          "type": "string",
                          "format": "uuid",
                          "description": "The author that was merged and deleted."
                        },
                        "into": {
                          "type": "string",
                          "format": "uuid",
                          "description": "The surviving author."
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/categories": {
      "get": {
        "operationId": "listCmsCategories",
        "summary": "List a site's CMS categories",
        "description": "List the FraseCMS categories for a site.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "description": "The site whose categories to list",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of categories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "categories": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "name": {
                                "type": "string"
                              },
                              "slug": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string",
                                "nullable": true
                              },
                              "parent_id": {
                                "type": "string",
                                "format": "uuid",
                                "nullable": true
                              },
                              "post_count": {
                                "type": "integer"
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      },
      "post": {
        "operationId": "createCmsCategory",
        "summary": "Create a CMS category",
        "description": "Create a FraseCMS category on a site. Pass `parent_id` to nest it under another category.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "name"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The site to create the category on."
                  },
                  "name": {
                    "type": "string",
                    "description": "Required. Category name."
                  },
                  "description": {
                    "type": "string",
                    "nullable": true
                  },
                  "parent_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true,
                    "description": "Optional parent category for nesting."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Category created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "category": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "name": {
                              "type": "string"
                            },
                            "slug": {
                              "type": "string"
                            },
                            "description": {
                              "type": "string",
                              "nullable": true
                            },
                            "parent_id": {
                              "type": "string",
                              "format": "uuid",
                              "nullable": true
                            },
                            "post_count": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/categories/{id}": {
      "patch": {
        "operationId": "updateCmsCategory",
        "summary": "Update a CMS category",
        "description": "Update a FraseCMS category. `site_id` is required to scope the lookup; other fields are optional.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Category ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The site the category belongs to."
                  },
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string",
                    "nullable": true
                  },
                  "parent_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Category updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "category": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "name": {
                              "type": "string"
                            },
                            "slug": {
                              "type": "string"
                            },
                            "description": {
                              "type": "string",
                              "nullable": true
                            },
                            "parent_id": {
                              "type": "string",
                              "format": "uuid",
                              "nullable": true
                            },
                            "post_count": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      },
      "delete": {
        "operationId": "deleteCmsCategory",
        "summary": "Delete a CMS category",
        "description": "Delete a FraseCMS category. Posts are unlinked rather than orphaned.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Category ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "description": "The site the category belongs to",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Category deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/categories/{id}/merge": {
      "post": {
        "operationId": "mergeCmsCategories",
        "summary": "Merge two CMS categories",
        "description": "Re-point every post from this category onto `merge_into`, then delete this category. Runs as one transaction.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Category ID to merge and delete",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "merge_into"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The site both categories belong to."
                  },
                  "merge_into": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The surviving category."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Categories merged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "merged": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "into": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/tags": {
      "get": {
        "operationId": "listCmsTags",
        "summary": "List a site's CMS tags",
        "description": "List the FraseCMS tags for a site.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "description": "The site whose tags to list",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of tags",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "tags": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "name": {
                                "type": "string"
                              },
                              "slug": {
                                "type": "string"
                              },
                              "post_count": {
                                "type": "integer"
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      },
      "post": {
        "operationId": "createCmsTag",
        "summary": "Create a CMS tag",
        "description": "Create a FraseCMS tag on a site.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "name"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The site to create the tag on."
                  },
                  "name": {
                    "type": "string",
                    "description": "Required. Tag name."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Tag created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "tag": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "name": {
                              "type": "string"
                            },
                            "slug": {
                              "type": "string"
                            },
                            "post_count": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/tags/{id}": {
      "patch": {
        "operationId": "updateCmsTag",
        "summary": "Update a CMS tag",
        "description": "Rename a FraseCMS tag. `site_id` scopes the lookup.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Tag ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "name"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The site the tag belongs to."
                  },
                  "name": {
                    "type": "string",
                    "description": "Required. New tag name."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tag updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "tag": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "name": {
                              "type": "string"
                            },
                            "slug": {
                              "type": "string"
                            },
                            "post_count": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      },
      "delete": {
        "operationId": "deleteCmsTag",
        "summary": "Delete a CMS tag",
        "description": "Delete a FraseCMS tag. Post links are cascade-unlinked.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Tag ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "description": "The site the tag belongs to",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tag deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/tags/{id}/merge": {
      "post": {
        "operationId": "mergeCmsTags",
        "summary": "Merge two CMS tags",
        "description": "De-duplicate and re-point post links from this tag onto `merge_into`, then delete this tag.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Tag ID to merge and delete",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "merge_into"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The site both tags belong to."
                  },
                  "merge_into": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The surviving tag."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tags merged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "merged": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "into": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/redirects": {
      "get": {
        "operationId": "listCmsRedirects",
        "summary": "List a site's redirects",
        "description": "List the FraseCMS redirects for a site, optionally filtered to those pointing at a given `to_path`.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "description": "The site whose redirects to list",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "to_path",
            "in": "query",
            "required": false,
            "description": "Only return redirects whose target is this path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of redirects",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "redirects": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "from_path": {
                                "type": "string"
                              },
                              "to_path": {
                                "type": "string"
                              },
                              "status_code": {
                                "type": "integer",
                                "description": "One of 301, 302, 307, 308."
                              },
                              "is_active": {
                                "type": "boolean"
                              },
                              "source": {
                                "type": "string",
                                "enum": [
                                  "manual",
                                  "import",
                                  "slug_change"
                                ],
                                "description": "How the redirect was created."
                              },
                              "created_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      },
      "post": {
        "operationId": "createCmsRedirect",
        "summary": "Create a redirect",
        "description": "Create a single manual redirect on a site. Paths are site-relative. Self-redirects and redirects that would create a loop are rejected.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "from_path",
                  "to_path"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The site to add the redirect to."
                  },
                  "from_path": {
                    "type": "string",
                    "description": "Required. Site-relative source path."
                  },
                  "to_path": {
                    "type": "string",
                    "description": "Required. Site-relative destination path."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Redirect created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "redirect": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "from_path": {
                              "type": "string"
                            },
                            "to_path": {
                              "type": "string"
                            },
                            "status_code": {
                              "type": "integer",
                              "description": "One of 301, 302, 307, 308."
                            },
                            "is_active": {
                              "type": "boolean"
                            },
                            "source": {
                              "type": "string",
                              "enum": [
                                "manual",
                                "import",
                                "slug_change"
                              ],
                              "description": "How the redirect was created."
                            },
                            "created_at": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/redirects/{id}": {
      "patch": {
        "operationId": "updateCmsRedirect",
        "summary": "Update a redirect",
        "description": "Update a redirect's target, status code, or active flag. `site_id` scopes the lookup. `status_code` must be one of 301, 302, 307, 308.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Redirect ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The site the redirect belongs to."
                  },
                  "to_path": {
                    "type": "string",
                    "description": "New destination path."
                  },
                  "status_code": {
                    "type": "integer",
                    "enum": [
                      301,
                      302,
                      307,
                      308
                    ],
                    "description": "New HTTP redirect status."
                  },
                  "is_active": {
                    "type": "boolean",
                    "description": "Enable or disable the redirect."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Redirect updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "redirect": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "from_path": {
                              "type": "string"
                            },
                            "to_path": {
                              "type": "string"
                            },
                            "status_code": {
                              "type": "integer",
                              "description": "One of 301, 302, 307, 308."
                            },
                            "is_active": {
                              "type": "boolean"
                            },
                            "source": {
                              "type": "string",
                              "enum": [
                                "manual",
                                "import",
                                "slug_change"
                              ],
                              "description": "How the redirect was created."
                            },
                            "created_at": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      },
      "delete": {
        "operationId": "deleteCmsRedirect",
        "summary": "Delete a redirect",
        "description": "Delete a redirect from a site.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Redirect ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "description": "The site the redirect belongs to",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Redirect deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/redirects/chains": {
      "get": {
        "operationId": "inspectCmsRedirectChains",
        "summary": "Diagnose redirect chains and loops",
        "description": "Inspect a site's redirects for multi-hop chains (a redirect that points at another redirect) and loops, so they can be flattened before they cost crawl budget.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "description": "The site to inspect",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Chain and loop findings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "issues": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "from_path": {
                                "type": "string",
                                "description": "The path that begins the chain or loop."
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "chain",
                                  "loop"
                                ]
                              },
                              "path": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "description": "The ordered hops from from_path onward."
                              },
                              "final_target": {
                                "type": "string",
                                "nullable": true,
                                "description": "The resolved destination for a chain; null for a loop."
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/redirects/import": {
      "post": {
        "operationId": "importCmsRedirects",
        "summary": "Bulk-import redirects",
        "description": "Bulk-load up to 1000 redirects for a site in one synchronous, last-wins upsert - e.g. a batch of legacy paths at migration. Paths must be site-relative, not absolute URLs, and at most 500 characters. Returns counts of created, updated, and skipped rows.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "redirects"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required. The site to import into."
                  },
                  "redirects": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 1000,
                    "description": "Required. Non-empty list of redirects, at most 1000.",
                    "items": {
                      "type": "object",
                      "required": [
                        "from_path",
                        "to_path"
                      ],
                      "properties": {
                        "from_path": {
                          "type": "string",
                          "description": "Site-relative source path."
                        },
                        "to_path": {
                          "type": "string",
                          "description": "Site-relative destination path."
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Import summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "created": {
                          "type": "integer"
                        },
                        "updated": {
                          "type": "integer"
                        },
                        "skipped": {
                          "type": "integer",
                          "description": "Rows that resolved to no-ops (e.g. self-redirects)."
                        },
                        "site_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/posts/{id}/versions": {
      "get": {
        "operationId": "listCmsPostVersions",
        "summary": "List a post's version history",
        "description": "List the saved editorial versions of a FraseCMS post, newest first. Each entry is a lightweight summary; fetch a single version for its full content.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Post ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of version summaries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "version": {
                            "type": "integer"
                          },
                          "title": {
                            "type": "string"
                          },
                          "slug": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string"
                          },
                          "change_description": {
                            "type": "string",
                            "nullable": true
                          },
                          "created_by_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/posts/{id}/versions/{versionId}": {
      "get": {
        "operationId": "getCmsPostVersion",
        "summary": "Get one post version",
        "description": "Retrieve a single saved version of a FraseCMS post, including its full editorial content and SEO fields as they were at capture time.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Post ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "versionId",
            "in": "path",
            "required": true,
            "description": "Version ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Version detail",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "version": {
                          "type": "integer"
                        },
                        "title": {
                          "type": "string"
                        },
                        "slug": {
                          "type": "string",
                          "nullable": true
                        },
                        "status": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "nullable": true
                        },
                        "content": {
                          "type": "string",
                          "nullable": true
                        },
                        "excerpt": {
                          "type": "string",
                          "nullable": true
                        },
                        "seo_title": {
                          "type": "string",
                          "nullable": true
                        },
                        "seo_description": {
                          "type": "string",
                          "nullable": true
                        },
                        "focus_keyword": {
                          "type": "string",
                          "nullable": true
                        },
                        "canonical_url": {
                          "type": "string",
                          "nullable": true
                        },
                        "featured_image": {
                          "type": "string",
                          "nullable": true
                        },
                        "change_description": {
                          "type": "string",
                          "nullable": true
                        },
                        "created_by_id": {
                          "type": "string",
                          "nullable": true
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/posts/{id}/versions/{versionId}/restore": {
      "post": {
        "operationId": "restoreCmsPostVersion",
        "summary": "Restore a post to an earlier version",
        "description": "Restore a post's editorial content (title, body, excerpt, SEO fields) to the given version. Status, type, and taxonomy are intentionally not reverted. The restore routes through the normal update path, so it re-runs the content-rules gate: on a live post, a rule violation returns 422 with the violations and a `retry_with_force` hint.",
        "tags": [
          "CMS"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Post ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "versionId",
            "in": "path",
            "required": true,
            "description": "Version ID to restore from",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The updated post",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CmsPost"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "Restoring this version would violate content rules on a live post",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "rules_blocked"
                      ]
                    },
                    "rule_violations": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "retry_with_force": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/rules/evaluate": {
      "post": {
        "operationId": "evaluateRuleSets",
        "summary": "Evaluate rule sets against content, a CMS post, or raw text",
        "description": "Run content rules against exactly one subject: an existing Frase content row (`content_id`), a FraseCMS post (`post_id`), or raw text (`content`). Omit `rule_set_id` to evaluate every enabled rule set (org-wide plus the subject's site), matching the in-app agent. This is a **read:content** endpoint: results are never persisted (the `save_results` field is accepted for back-compat but ignored). Provide `target_keywords` (post/raw subjects) to compute real SEO/GEO/EEAT scores for score_threshold rules; without it those rules report `skipped` rather than failing.",
        "tags": [
          "Rules"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Subject: an existing Frase content row."
                  },
                  "post_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Subject: a FraseCMS post."
                  },
                  "content": {
                    "type": "object",
                    "description": "Subject: raw text (e.g. a pre-publish preflight).",
                    "required": [
                      "body"
                    ],
                    "properties": {
                      "title": {
                        "type": "string"
                      },
                      "body": {
                        "type": "string",
                        "description": "Required. Sanitized exactly as a publish would before evaluation."
                      },
                      "seo_title": {
                        "type": "string"
                      },
                      "seo_description": {
                        "type": "string"
                      }
                    }
                  },
                  "rule_set_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional. Omit to evaluate every enabled rule set in scope."
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional. Scopes site-scoped rule sets and score computation."
                  },
                  "target_keywords": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Optional (post/raw subjects). Enables real score computation for score_threshold rules."
                  },
                  "save_results": {
                    "type": "boolean",
                    "description": "Accepted for back-compat but IGNORED — this read-scope endpoint never persists."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Evaluation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "content_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Echoed when the subject was a content row."
                        },
                        "post_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Echoed when the subject was a FraseCMS post."
                        },
                        "overall_status": {
                          "type": "string",
                          "enum": [
                            "pass",
                            "warning",
                            "fail"
                          ]
                        },
                        "no_rules_configured": {
                          "type": "boolean",
                          "description": "true when no rule set applied — a 'pass' here means governance was never set up, not that anything was checked."
                        },
                        "site_scoped_sets_skipped": {
                          "type": "integer",
                          "description": "Count of site-scoped rule sets not evaluated (no site in scope). A verdict with this > 0 is weaker than the publish gate."
                        },
                        "rule_set_results": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "rule_set_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "rule_set_name": {
                                "type": "string"
                              },
                              "overall_status": {
                                "type": "string",
                                "enum": [
                                  "pass",
                                  "warning",
                                  "fail"
                                ]
                              },
                              "summary": {
                                "nullable": true
                              },
                              "results": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "rule_id": {
                                      "type": "string",
                                      "format": "uuid"
                                    },
                                    "rule_name": {
                                      "type": "string"
                                    },
                                    "condition_type": {
                                      "type": "string"
                                    },
                                    "severity": {
                                      "type": "string",
                                      "enum": [
                                        "error",
                                        "warning",
                                        "info"
                                      ]
                                    },
                                    "passed": {
                                      "type": "boolean"
                                    },
                                    "skipped": {
                                      "type": "boolean",
                                      "description": "The rule could not run (e.g. a score_threshold rule with no target_keywords). A skipped rule is neither a pass nor a failure — never read it as a genuine pass."
                                    },
                                    "value": {
                                      "nullable": true
                                    },
                                    "threshold": {
                                      "nullable": true
                                    },
                                    "message": {
                                      "type": "string",
                                      "nullable": true
                                    },
                                    "fix_hint": {
                                      "type": "string",
                                      "nullable": true
                                    }
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/brand-context": {
      "get": {
        "operationId": "getBrandContext",
        "summary": "Get the brand governance bundle for on-brand authoring",
        "description": "The same brand bundle the in-app agent gets injected into its prompt — brand voice, terminology, reference context, approved brand records, and a language note — so an external agent can author on-brand BEFORE writing. The read-side twin of the publish-time rules gate. Each section is a prompt-ready string; an absent (null) section means the org hasn't configured it (reference_context also needs a `topic` relevant to a reference doc).",
        "tags": [
          "Brand"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional. Scopes site-specific brand config."
          },
          {
            "name": "topic",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional. Surfaces reference context relevant to this topic."
          }
        ],
        "responses": {
          "200": {
            "description": "Brand governance bundle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "site_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true
                        },
                        "topic": {
                          "type": "string",
                          "nullable": true
                        },
                        "brand_voice": {
                          "type": "string",
                          "nullable": true
                        },
                        "terminology": {
                          "type": "string",
                          "nullable": true
                        },
                        "reference_context": {
                          "type": "string",
                          "nullable": true
                        },
                        "approved_brand": {
                          "type": "string",
                          "nullable": true
                        },
                        "language_note": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/brand-context/terminology": {
      "post": {
        "operationId": "checkTerminology",
        "summary": "Check raw text against brand terminology",
        "description": "Term compliance on raw text (no content row needed) — the same check the in-app agent's terminology tool runs and the same evaluator the publish gate's term_compliance rules use, so a clean preflight here means that rule passes at publish. **read:content** scope; nothing is persisted.",
        "tags": [
          "Brand"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "description": "Required, non-empty. The text to check."
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional. Scopes site-specific terms."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Term compliance report",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "has_terms": {
                          "type": "boolean",
                          "description": "Whether the org has any brand terms configured."
                        },
                        "is_compliant": {
                          "type": "boolean"
                        },
                        "violations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "term": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string"
                              },
                              "replacement": {
                                "type": "string",
                                "nullable": true
                              },
                              "positions": {
                                "type": "array",
                                "items": {
                                  "type": "integer"
                                }
                              },
                              "context": {
                                "type": "string",
                                "nullable": true
                              }
                            }
                          }
                        },
                        "preferred_terms_used": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "suggestions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "original": {
                                "type": "string"
                              },
                              "suggested": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/posts/by-slug": {
      "get": {
        "operationId": "getCmsPostBySlug",
        "summary": "Get a CMS post by slug",
        "description": "Retrieve a single CMS post by its human-readable slug within a site. Use when you know the published slug but not the post UUID. Org-scoped to the API key; a site_id from another organization yields 404.",
        "tags": [
          "CMS"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Site the post belongs to"
          },
          {
            "name": "slug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Post slug, e.g. \"my-first-post\""
          }
        ],
        "responses": {
          "200": {
            "description": "Post details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CmsPost"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/cms/{deliveryToken}/posts": {
      "servers": [
        {
          "url": "https://next.frase.io/api",
          "description": "Production"
        },
        {
          "url": "http://localhost:3000/api",
          "description": "Local Development"
        }
      ],
      "get": {
        "operationId": "listDeliveryPosts",
        "summary": "List published posts (headless delivery)",
        "description": "Public, token-gated headless delivery. Returns published posts for the site identified by the fcms_ delivery token. No API key; the token in the path both identifies and authorizes the site. Rate-limited per-IP and per-site; metered against the site's monthly view allowance.",
        "tags": [
          "CMS Delivery (Public)"
        ],
        "security": [],
        "parameters": [
          {
            "name": "deliveryToken",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Per-site fcms_-prefixed delivery token (from CMS settings). Replaces the raw siteId in the path; identifies AND authorizes the site."
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "blog_post",
                "page"
              ],
              "default": "blog_post"
            },
            "description": "Post type filter"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 100
            },
            "description": "Page size (max 100)"
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            },
            "description": "Pagination offset"
          },
          {
            "name": "updated_since",
            "in": "query",
            "required": false,
            "description": "ISO 8601 instant. Returns only posts with updated_at >= this (incremental sync). Combines with type/limit/offset. A malformed value returns 400 before any DB read.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter published posts by category slug, site-scoped (a slug from another site never matches). Exact match only in v1 (no descendant/hierarchy inclusion). Combines with type/limit/offset/sort/updated_since/tag. An unknown or never-matching slug returns an empty posts array with 200, not a 404. Has its own ETag and metering dedup key (no cross-filter 304).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "Filter published posts by tag slug, site-scoped (a slug from another site never matches). Combines with type/limit/offset/sort/updated_since/category. An unknown or never-matching slug returns an empty posts array with 200, not a 404. Has its own ETag and metering dedup key (no cross-filter 304).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "required": false,
            "description": "Conditional GET. When it matches the response ETag, the API returns 304 Not Modified (empty body, ETag still set) and does not meter the request.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Published posts. Carries an ETag (sha1 of the page's id + updated_at); send it back as If-None-Match for a 304 when nothing changed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "posts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CmsDeliveryPostSummary"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        },
                        "hasMore": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "updated_since is not a valid ISO 8601 date.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "304": {
            "description": "Not Modified. If-None-Match matched the current ETag; empty body, ETag header still set.",
            "headers": {
              "ETag": {
                "description": "The content-version ETag.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid fcms_ delivery token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "invalid_delivery_token"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Site is over its monthly view limit (quota block, distinct from the transient 429 rate limit)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "view_limit_exceeded",
                        "spend_cap_reached"
                      ],
                      "example": "view_limit_exceeded"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "CMS not enabled for this site, or post not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          },
          "503": {
            "description": "Subscription inactive, delivery temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Service temporarily unavailable"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cms/{deliveryToken}/posts/{slug}": {
      "servers": [
        {
          "url": "https://next.frase.io/api",
          "description": "Production"
        },
        {
          "url": "http://localhost:3000/api",
          "description": "Local Development"
        }
      ],
      "get": {
        "operationId": "getDeliveryPostBySlug",
        "summary": "Get a published post by slug (headless delivery)",
        "description": "Public, token-gated headless delivery of a single published post by slug. Same token/rate-limit/metering model as the list endpoint.",
        "tags": [
          "CMS Delivery (Public)"
        ],
        "security": [],
        "parameters": [
          {
            "name": "deliveryToken",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Per-site fcms_-prefixed delivery token (from CMS settings). Replaces the raw siteId in the path; identifies AND authorizes the site."
          },
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Post slug"
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "required": false,
            "description": "Conditional GET. When it matches the response ETag (\"<id>-<updatedAt ISO>\"), the API returns 304 Not Modified (empty body, ETag still set) and does not meter the request.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The published post. Carries an ETag of the form \"<id>-<updatedAt ISO>\"; send it back as If-None-Match for a 304 when unchanged.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "post": {
                      "$ref": "#/components/schemas/CmsDeliveryPost"
                    }
                  }
                }
              }
            }
          },
          "304": {
            "description": "Not Modified. If-None-Match matched the current ETag; empty body, ETag header still set.",
            "headers": {
              "ETag": {
                "description": "The content-version ETag.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid fcms_ delivery token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "invalid_delivery_token"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Site is over its monthly view limit (quota block, distinct from the transient 429 rate limit)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "view_limit_exceeded",
                        "spend_cap_reached"
                      ],
                      "example": "view_limit_exceeded"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "CMS not enabled for this site, or post not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          },
          "503": {
            "description": "Subscription inactive, delivery temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Service temporarily unavailable"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/sites": {
      "get": {
        "operationId": "listSites",
        "summary": "List sites",
        "description": "Retrieve all websites associated with your organization.",
        "tags": [
          "Sites"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of sites",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedSites"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      },
      "post": {
        "operationId": "createSite",
        "summary": "Create site",
        "description": "Create a new website to track and manage content for.",
        "tags": [
          "Sites"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSiteInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Site created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteCreated"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)"
          }
        }
      }
    },
    "/content": {
      "get": {
        "operationId": "listContent",
        "summary": "List content",
        "description": "Retrieve all content articles in your organization.",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "generating",
                "review",
                "published",
                "archived"
              ]
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "is_monitored",
            "in": "query",
            "description": "Filter by Content Guard monitoring state. 'true' returns only guarded articles, 'false' returns only un-guarded. Omit for no filter.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "scheduled_after",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only rows scheduled at or after this ISO 8601 datetime. Setting either bound excludes unscheduled rows and orders results by scheduled_at ascending."
          },
          {
            "name": "scheduled_before",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only rows scheduled at or before this ISO 8601 datetime."
          }
        ],
        "responses": {
          "200": {
            "description": "List of content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedContent"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/content/generate": {
      "post": {
        "operationId": "generateContent",
        "summary": "Generate content from brief",
        "description": "Generate content from an existing brief. The brief must have a complete outline. The content generation runs asynchronously - use the returned content ID with the jobs endpoint to track progress.",
        "tags": [
          "Content"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brief_id"
                ],
                "properties": {
                  "brief_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID of the brief to generate content from. The brief must have a non-empty outline."
                  },
                  "generate_images": {
                    "type": "boolean",
                    "default": false,
                    "description": "Generate a hero image for the content. Uses hero image credits."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Content generation started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Content ID"
                        },
                        "brief_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Brief ID"
                        },
                        "title": {
                          "type": "string",
                          "description": "Content title (from brief topic)"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "generating"
                          ],
                          "description": "Content status"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "content_url": {
                          "type": "string",
                          "description": "URL to view the content in the Frase app"
                        },
                        "status_url": {
                          "type": "string",
                          "description": "URL to check generation status"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Refused because the organization's SUBSCRIPTION is not in good standing (`subscription_inactive`): canceled, paused, past due beyond the grace period, or an expired trial. Nothing is generated and no credit is spent.\n\nThis is NOT a quota refusal, and none of the quota remedies clear it: waiting for the monthly reset, enabling paid overage and upgrading the plan all leave it refused. The `message` names the account state; an organization admin resolves it in Billing settings.\n\nThe same status also carries the AUTH-layer refusals, which are about the KEY rather than the account: `insufficient_scope` (the key lacks `write:content`), `ip_not_allowed` (the request came from an address outside the key's allowlist), and `key_missing_user` (the key has no associated user and must be regenerated). Branch on `error.code`, not on the status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "type": "permission_error",
                    "code": "subscription_inactive",
                    "message": "Your payment is past due. Please add a valid payment method to restore access.",
                    "doc_url": "https://docs.frase.io/api/errors#subscription_inactive"
                  },
                  "request_id": "req_abc123"
                }
              }
            }
          },
          "404": {
            "description": "Brief not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Refused for a quota: the organization's monthly article allowance (`article_limit_exceeded`), the SITE's own monthly article budget (`site_article_budget_exceeded`), or the monthly hero image allowance (`hero_image_limit_exceeded`). Nothing is generated and no credit is spent, and a retry cannot succeed until the relevant cap changes.\n\n`site_article_budget_exceeded` is a separate cap from the organization allowance: paid overage and plan upgrades do NOT lift it, and it can refuse while the organization has plenty of articles left. An organization admin raises it in Site settings, or you can generate for a different site.\n\n`rate_limit_exceeded` is a different thing entirely and DOES clear on a clock: generation is capped at 30 calls per hour for each key owner in an organization, and this response carries `Retry-After` (seconds) plus the `X-RateLimit-*` headers. Wait out the window and retry.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "example": "rate_limit_error"
                        },
                        "code": {
                          "type": "string",
                          "enum": [
                            "article_limit_exceeded",
                            "site_article_budget_exceeded",
                            "hero_image_limit_exceeded",
                            "rate_limit_exceeded"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "doc_url": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/content/{id}": {
      "get": {
        "operationId": "getContent",
        "summary": "Get content",
        "description": "Retrieve a specific content article by ID.",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Content details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Content"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "operationId": "updateContent",
        "summary": "Update content",
        "description": "Update content title, body, or metadata.",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "body": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "draft",
                      "review",
                      "published",
                      "archived"
                    ]
                  },
                  "meta_title": {
                    "type": "string"
                  },
                  "meta_description": {
                    "type": "string"
                  },
                  "target_keywords": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 25,
                    "nullable": true,
                    "description": "Replaces the article's keywords. null or [] clears them; omit the field to leave them alone. Beyond 25 the list is truncated and the stored result is echoed back."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Content updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "title": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "word_count": {
                          "type": "integer"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "operationId": "deleteContent",
        "summary": "Delete content",
        "description": "Soft delete content (moves to trash).",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Content deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "boolean"
                        },
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/content/{id}/status": {
      "get": {
        "operationId": "getContentStatus",
        "summary": "Get content generation status",
        "description": "Check the status of content generation.",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Content status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentStatus"
                }
              }
            }
          }
        }
      }
    },
    "/content/{id}/export": {
      "get": {
        "operationId": "exportContent",
        "summary": "Export content",
        "description": "Export content in various formats.",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "html",
                "markdown"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Exported content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentExport"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/content/{id}/publish": {
      "post": {
        "operationId": "publishContent",
        "summary": "Publish content to CMS",
        "description": "Publish content to a connected CMS platform (Frase CMS, WordPress, Webflow, or Sanity). The content must exist and the CMS must be connected to the specified site.",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Content ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "destination",
                  "site_id"
                ],
                "properties": {
                  "destination": {
                    "type": "string",
                    "enum": [
                      "frase_cms",
                      "wordpress",
                      "webflow",
                      "sanity"
                    ],
                    "description": "Target CMS platform"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Site ID with the CMS connection"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "publish",
                      "draft"
                    ],
                    "default": "publish",
                    "description": "Publish status. DEFAULT IS \"publish\" (goes live) - pass \"draft\" to save without publishing. Cannot be combined with scheduled_at (400): the server schedules a LIVE publish whenever scheduled_at is set."
                  },
                  "scheduled_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "UTC (Z-suffixed) ISO 8601 datetime. Offset forms (+02:00) are rejected (400)."
                  },
                  "force": {
                    "type": "boolean",
                    "default": false,
                    "description": "Publish even if the content has rule warnings (rule ERRORS still block)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "400": {
            "description": "Validation failure: status draft combined with scheduled_at, or a non-UTC/malformed scheduled_at"
          },
          "200": {
            "description": "Content published successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean"
                        },
                        "destination": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string",
                          "nullable": true,
                          "description": "Live URL of the published item. For frase_cms this is derived from the site's CURRENT CMS settings (subdomain, active custom domain, or subdirectory host) and is the same value stored on the content row and sent in the content.published webhook; null when no domain is configured yet."
                        },
                        "external_id": {
                          "type": "string",
                          "nullable": true,
                          "description": "External CMS item ID"
                        },
                        "live_publish_failed": {
                          "type": "boolean",
                          "description": "Webflow only, present only when true. The CMS item was written but Webflow refused the site-level publish, so NOTHING is live and `url` is null. The write itself succeeded, which is why this is a 200 and not an error — but the item is not readable until the site is published in Webflow. See `live_publish_message` for the reason."
                        },
                        "live_publish_message": {
                          "type": "string",
                          "description": "Present alongside `live_publish_failed`: what still has to happen for the item to go live, including Webflow's own sentence where it gave a usable one."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "409": {
            "description": "State conflict. Either the content type is review-gated and the post is not approved yet (review_required), or a scheduled publish was requested for an article Frase is still writing (still_generating) - arming a schedule captures the article body, so a half-written article would publish empty. Both clear on their own: approve the post, or wait for generation to finish.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "review_required",
                        "still_generating"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/content/{id}/unschedule": {
      "post": {
        "operationId": "unscheduleContent",
        "summary": "Clear a scheduled publish",
        "description": "Clears an armed publish schedule without publishing. Idempotent: unscheduling an article with no schedule succeeds. A scheduled_via 'plan' row is a content-plan generation promise and is refused with code plan_scheduled rather than unplanned. If the schedule already fired, responds 409 already_published_remotely with the live URL.",
        "tags": [
          "Content"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Content ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Schedule cleared (or nothing was scheduled)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "unscheduled": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The site's CMS connection is missing or invalid (codes no_connection, invalid_connection); permanent until reconnected"
          },
          "404": {
            "description": "Content not found"
          },
          "409": {
            "description": "Refused as a truth conflict: the schedule already fired (code already_published_remotely, published_url carries the live URL) or the date is a content-plan promise (code plan_scheduled)"
          },
          "502": {
            "description": "The connected CMS refused the disarm and the schedule may still fire (code publish_failed)"
          }
        }
      }
    },
    "/content/{id}/regenerate": {
      "post": {
        "operationId": "regenerateContent",
        "summary": "Regenerate or improve content",
        "description": "Regenerate content from its brief (full regeneration) or improve it with specific instructions. When instructions are provided, the content is rewritten using AI with those instructions. Without instructions, the content is fully regenerated from its brief. Both operations run asynchronously.",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Content ID"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instructions": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Improvement instructions for AI rewriting. If omitted, content is fully regenerated from its brief."
                  },
                  "brief_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Brief ID to regenerate from. Uses the content's linked brief if not specified."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Regeneration started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "generating",
                            "improving"
                          ]
                        },
                        "brief_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status_url": {
                          "type": "string",
                          "description": "URL to check generation status"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Refused because the organization's SUBSCRIPTION is not in good standing (`subscription_inactive`): canceled, paused, past due beyond the grace period, or an expired trial. Nothing is regenerated and no credit is spent, and none of the quota remedies clear it — an organization admin resolves it in Billing settings.\n\nThe same status also carries the AUTH-layer refusals, which are about the KEY rather than the account: `insufficient_scope` (the key lacks `write:content`), `ip_not_allowed` (the request came from an address outside the key's allowlist), and `key_missing_user` (the key has no associated user and must be regenerated). Branch on `error.code`, not on the status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "type": "permission_error",
                    "code": "subscription_inactive",
                    "message": "Your payment is past due. Please add a valid payment method to restore access.",
                    "doc_url": "https://docs.frase.io/api/errors#subscription_inactive"
                  },
                  "request_id": "req_abc123"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "description": "Refused for a quota: the organization's monthly article allowance (`article_limit_exceeded`) or the SITE's own monthly article budget (`site_article_budget_exceeded`). A full regeneration spends from the same allowance a fresh generation does — except when the article was already charged in the current billing period, which is free and never refused for quota. Nothing is regenerated and no credit is spent.\n\n`site_article_budget_exceeded` is a separate cap from the organization allowance: paid overage and plan upgrades do NOT lift it. An organization admin raises it in Site settings.\n\n`rate_limit_exceeded` is a different thing entirely and DOES clear on a clock: full regeneration (a request with no `instructions`) is capped at 30 calls per hour for each key owner in an organization, and this response carries `Retry-After` (seconds) plus the `X-RateLimit-*` headers. It is what bounds the free case above — a rewrite the billing period already paid for costs nothing, so the hourly cap is the only limit on repeating it. Requests WITH `instructions` take the improvement path and are not subject to it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "example": "rate_limit_error"
                        },
                        "code": {
                          "type": "string",
                          "enum": [
                            "article_limit_exceeded",
                            "site_article_budget_exceeded",
                            "rate_limit_exceeded"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/content/{id}/generate-image": {
      "post": {
        "operationId": "generateContentHeroImage",
        "summary": "Generate a hero image for existing content",
        "description": "Queue one AI hero image for an article that already exists and attach it as the featured image. The article body, brief and meta are never touched, so edits made after generation are kept. Runs asynchronously: a render takes 20 to 60 seconds. Poll GET /content/{id}: `progress_details.heroImageStatus` goes `queued` then `completed` (image on `featured_image`) or `failed` (`heroImageFailureReason` says why; stop polling). Uses one image credit and one AI-image unit of the site budget, both reserved at request time and refunded exactly once if the render fails. Refuses with 409 when the article already has a hero image unless `replace` is true.",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Content ID"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "replace": {
                    "type": "boolean",
                    "default": false,
                    "description": "Overwrite an existing hero image. Off by default so an automated pipeline never silently replaces a picture someone chose by hand."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Hero image generation queued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "queued"
                          ]
                        },
                        "replace": {
                          "type": "boolean"
                        },
                        "request_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "This request's receipt id. The article's `progress_details.heroImageRequestId` names the request that last wrote its hero status; compare the two so a concurrent request's outcome is never read as this one's."
                        },
                        "previous_featured_image": {
                          "type": "string",
                          "nullable": true,
                          "description": "The hero image on the article when the request was accepted, or null. With `replace`, the old picture stays up until the new one lands, so poll until `featured_image` differs from this value."
                        },
                        "poll_url": {
                          "type": "string",
                          "description": "GET this until `progress_details.heroImageStatus` is `completed` with `heroImageRequestId` equal to `request_id` (and, on a replace, `featured_image` differs from `previous_featured_image`). `failed` for this request id, with `heroImageFailureReason`, means the render will not arrive; stop polling."
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid content ID, invalid body, or the content has no body text yet to write a prompt from"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "AI images are turned off for this content's site (`ai_images_disabled`)"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The content already has a hero image and `replace` was not true (`hero_image_exists`)"
          },
          "429": {
            "description": "No image credits left (`image_credits_exhausted`, no Retry-After: the allowance resets monthly), or the per-caller generation rate limit (`rate_limit_exceeded`, carries Retry-After)"
          }
        }
      }
    },
    "/content/{id}/rescore": {
      "post": {
        "operationId": "rescoreContent",
        "summary": "Recalculate content scores",
        "description": "Recalculate SEO, GEO, and EEAT scores for a content item. This is a lightweight, synchronous operation (~50ms) that uses zero external API calls. Scores are persisted to the database. Available on all plans.",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Content ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Scores recalculated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "scores": {
                          "type": "object",
                          "properties": {
                            "seo_score": {
                              "type": "integer",
                              "minimum": 0,
                              "maximum": 100
                            },
                            "seo_breakdown": {
                              "type": "object"
                            },
                            "geo_score": {
                              "type": "integer",
                              "minimum": 0,
                              "maximum": 100
                            },
                            "geo_breakdown": {
                              "type": "object"
                            },
                            "eeat_score": {
                              "type": "integer",
                              "minimum": 0,
                              "maximum": 100
                            },
                            "eeat_breakdown": {
                              "type": "object"
                            }
                          }
                        },
                        "rescored_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Content has no body to score",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "retry_after": {
                      "type": "integer",
                      "description": "Seconds until rate limit resets"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/content/{id}/monitoring": {
      "get": {
        "operationId": "getContentMonitoring",
        "summary": "Get Content Guard monitoring status",
        "description": "Content Guard monitoring state for one article. `hasPublishedUrl` is a RECOVERABILITY judgment, not a presence test on the stored URL: the server runs the same recovery ladder arming runs — the stored URL when absolute; otherwise (empty slot, non-FraseCMS) the newest live CMS-inventory URL; otherwise, for a FraseCMS article with a live published post, an address re-derived from the site's CURRENT settings. So a stored relative path (\"/blog/post\", which a FraseCMS publish produces before domain setup) reports `hasPublishedUrl: true` once domain setup is finished — no re-publish needed — and `false` means the enable WOULD be rejected right now. `publishedUrlIssue` names the residual after recovery failed: \"missing\" (no stored URL and nothing recoverable) or \"not_absolute\" (a stored path that could not be re-derived — for FraseCMS that can mean domain setup unfinished, the post not live, or FraseCMS disabled for the site). Read the pair together rather than testing the URL yourself: this is exactly the condition enabling enforces.",
        "tags": [
          "Optimizations"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Content ID."
          }
        ],
        "responses": {
          "200": {
            "description": "Monitoring status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "isMonitored": {
                          "type": "boolean",
                          "description": "Whether Content Guard is currently watching this article."
                        },
                        "monitoredAt": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true,
                          "description": "When monitoring was first enabled, or null when it never was."
                        },
                        "quota": {
                          "type": "object",
                          "description": "The workspace's monitoring quota after this read.",
                          "properties": {
                            "used": {
                              "type": "integer"
                            },
                            "limit": {
                              "type": "integer",
                              "description": "Monitored-content cap on the current plan. A sentinel 999 means unlimited."
                            },
                            "remaining": {
                              "type": "integer"
                            },
                            "allowed": {
                              "type": "boolean",
                              "description": "Whether another article could be guarded right now."
                            },
                            "message": {
                              "type": "string",
                              "description": "Present only when the quota blocks further arming."
                            }
                          }
                        },
                        "hasPublishedUrl": {
                          "type": "boolean",
                          "description": "Whether Guard could watch this article RIGHT NOW: the stored URL when absolute, or an address the server can recover (CMS inventory, or FraseCMS re-derivation from current settings when a live published post exists). True no longer implies the stored URL itself is absolute. This is the same ladder the enable path runs, so it never reports true for an article that arming would reject."
                        },
                        "publishedUrlIssue": {
                          "type": "string",
                          "nullable": true,
                          "enum": [
                            "missing",
                            "not_absolute",
                            null
                          ],
                          "description": "Residual reason when hasPublishedUrl is false — i.e. after recovery failed. \"missing\": no stored URL and nothing recoverable (never published, or a FraseCMS article with no live post/domain). \"not_absolute\": a stored path that could not be re-derived — for FraseCMS that can mean domain setup unfinished, the post not live, or FraseCMS disabled; for imports, a URL that was never a full address."
                        },
                        "hasGsc": {
                          "type": "boolean",
                          "description": "Whether the article's site has a connected Search Console property."
                        },
                        "cmsConnections": {
                          "type": "array",
                          "description": "CMS destinations this article could be re-published to.",
                          "items": {
                            "type": "object"
                          }
                        },
                        "pendingApplicationId": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true,
                          "description": "A suggestion application awaiting review, or null."
                        },
                        "isPaused": {
                          "type": "boolean",
                          "description": "True when this article is monitored but ranks past the plan's quota, so the sweep skips it. Ephemeral: it clears on upgrade without any data change."
                        },
                        "unreachableSince": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true,
                          "description": "When the guarded URL stopped answering. Set only after two consecutive failed weekly runs, so it means \"this page appears to be gone\", not \"one request timed out\". Null while the page still answers, and null whenever monitoring is off."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Content not found in this workspace"
          }
        }
      },
      "post": {
        "operationId": "setContentMonitoring",
        "summary": "Enable or disable Content Guard monitoring",
        "description": "Enable or disable Content Guard monitoring. Enabling needs an address Guard can watch, resolved by a recovery ladder: the stored URL when absolute; otherwise (empty slot, non-FraseCMS) the newest live CMS-inventory URL (persisted when absolute); otherwise, for a FraseCMS article with a live published post and a configured domain, an address re-derived from the site's CURRENT settings (persisted). A relative stored URL is therefore NOT a refusal by itself — a FraseCMS article published before domain setup becomes armable the moment setup finishes, with no re-publish. Refusals: `NO_PUBLISHED_URL` when the slot is empty and nothing was recoverable (note this can include a published article whose publish stored no URL); `UNUSABLE_PUBLISHED_URL` when a stored value exists but no ladder leg produced an absolute address. Enabling is quota-checked against the plan's monitored-articles limit; disabling never needs a URL. A no-op re-assert of the current state still returns 200 and does not rewrite monitoredAt. A successful enable can carry a `warning` (e.g. the initial reachability probe failed) without failing the request.",
        "tags": [
          "Optimizations"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Content ID."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "enable"
                ],
                "properties": {
                  "enable": {
                    "type": "boolean",
                    "description": "True to arm Content Guard, false to turn it off."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Monitoring toggled",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "is_monitored": {
                          "type": "boolean"
                        },
                        "quota_used": {
                          "type": "integer"
                        },
                        "quota_limit": {
                          "type": "integer"
                        },
                        "quota_unlimited": {
                          "type": "boolean",
                          "description": "True when the plan has no monitoring cap. Use this instead of comparing quota_limit to the sentinel."
                        },
                        "warning": {
                          "type": "string",
                          "description": "Present only when Guard armed but the published URL did not answer. Advisory: monitoring IS on."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or unusable published URL (NO_PUBLISHED_URL, UNUSABLE_PUBLISHED_URL), or a malformed body"
          },
          "403": {
            "description": "Monitoring quota exceeded for the current plan"
          },
          "404": {
            "description": "Content not found in this workspace"
          }
        }
      }
    },
    "/sites/{siteId}/cms-connections": {
      "get": {
        "operationId": "listCmsConnections",
        "summary": "List CMS connections",
        "description": "List the connection status of all supported CMS platforms (Frase CMS, WordPress, Webflow, Sanity) for a given site.",
        "tags": [
          "Sites"
        ],
        "parameters": [
          {
            "name": "siteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Site ID"
          }
        ],
        "responses": {
          "200": {
            "description": "CMS connection statuses",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "connections": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "platform": {
                                "type": "string",
                                "enum": [
                                  "frase_cms",
                                  "wordpress",
                                  "webflow",
                                  "sanity"
                                ]
                              },
                              "connected": {
                                "type": "boolean"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/briefs": {
      "get": {
        "operationId": "listBriefs",
        "summary": "List briefs",
        "description": "Retrieve all content briefs.",
        "tags": [
          "Briefs"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "pending",
                "research",
                "ready",
                "generating",
                "completed"
              ]
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter briefs by site ID"
          }
        ],
        "responses": {
          "200": {
            "description": "List of briefs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "topic": {
                            "type": "string"
                          },
                          "target_keywords": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "content_type": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "search_intent": {
                            "type": "string",
                            "nullable": true
                          },
                          "target_word_count": {
                            "type": "integer",
                            "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
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createBrief",
        "summary": "Create brief",
        "description": "Create a content brief from a completed research session. The brief is generated from the full research context (keywords, SERP headings, content gaps, evidence, AI visibility, search intent) using the same pipeline as the Frase app. The brief is created immediately with `status: \"pending\"` and populated asynchronously. Poll `status_url` to check when the outline is ready.",
        "tags": [
          "Briefs"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "research_session_id"
                ],
                "properties": {
                  "research_session_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID of a completed research session (from POST /research). The brief topic, keywords, and outline are generated from the research data."
                  },
                  "content_type": {
                    "type": "string",
                    "enum": [
                      "blog",
                      "guide",
                      "landing",
                      "product",
                      "comparison"
                    ],
                    "default": "blog",
                    "description": "Content type for the brief"
                  },
                  "target_word_count": {
                    "type": "integer",
                    "minimum": 500,
                    "maximum": 10000,
                    "default": 2000,
                    "description": "Target word count for the article"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A brief already exists for this research session — reused, not recreated. `research_updated_since_generation: true` means the research changed after the brief was generated (the brief is STALE); rebuild it via POST /briefs/{id}/regenerate.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string"
                        },
                        "brief_url": {
                          "type": "string"
                        },
                        "existing_brief": {
                          "type": "boolean"
                        },
                        "research_updated_since_generation": {
                          "type": "boolean"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Brief created. When `research_session_id` is provided, the brief is created with `status: \"pending\"` and will be populated asynchronously with the research-backed content plan. Poll `status_url` to check progress.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "topic": {
                          "type": "string"
                        },
                        "target_keywords": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "content_type": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "description": "Brief status. 'pending' when created from research (outline generating). 'draft' for standard briefs without auto-outline. 'ready' when outline is complete."
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "brief_url": {
                          "type": "string",
                          "description": "URL to view the brief in the Frase app"
                        },
                        "status_url": {
                          "type": "string",
                          "nullable": true,
                          "description": "URL to poll for outline generation status"
                        },
                        "research_session_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true,
                          "description": "Research session ID (present when brief was created from research)"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Brief generation already in progress for this research session"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/briefs/{id}": {
      "get": {
        "operationId": "getBrief",
        "summary": "Get brief",
        "description": "Retrieve a specific brief by ID. The outline field contains sections in snake_case format.",
        "tags": [
          "Briefs"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Brief details including outline sections",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "topic": {
                          "type": "string"
                        },
                        "target_keywords": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "content_type": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "search_intent": {
                          "type": "string",
                          "nullable": true
                        },
                        "target_word_count": {
                          "type": "integer",
                          "nullable": true
                        },
                        "evidence_budget": {
                          "type": "object",
                          "description": "What this brief's evidence supports, in words. An article encodes an evidence set: words past what the research carries become repetition, generic filler or invention. Counts the plan's own points together with the fact ledger, deduped — an imported brief keeps its evidence only in the ledger, and ledger rows are minted from plan evidence, so either source read alone is wrong in a different direction. Rejected facts are excluded. Advisory: nothing refuses a target on this basis.",
                          "properties": {
                            "points": {
                              "type": "number",
                              "description": "Distinct checkable propositions behind this brief."
                            },
                            "supports_words": {
                              "type": "integer",
                              "description": "Roughly how many words those points carry."
                            },
                            "target_words": {
                              "type": "integer",
                              "nullable": true
                            },
                            "supported": {
                              "type": "boolean",
                              "nullable": true,
                              "description": "Whether target_words sits inside what the evidence carries. Null when no target is set — \"unsupported\" would read as a finding where none was made."
                            }
                          }
                        },
                        "outline": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ContentOutlineSection"
                          }
                        },
                        "competitor_urls": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "notes": {
                          "type": "string",
                          "nullable": true
                        },
                        "questions_to_answer": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "unique_angle": {
                          "type": "string",
                          "nullable": true
                        },
                        "target_language": {
                          "type": "string",
                          "nullable": true
                        },
                        "target_country": {
                          "type": "string",
                          "nullable": true
                        },
                        "authority_source": {
                          "type": "string",
                          "nullable": true
                        },
                        "blog_format": {
                          "type": "string",
                          "nullable": true
                        },
                        "guide_format": {
                          "type": "string",
                          "nullable": true
                        },
                        "is_imported": {
                          "type": "boolean"
                        },
                        "imported_content_url": {
                          "type": "string",
                          "nullable": true
                        },
                        "progress_details": {
                          "type": "object",
                          "nullable": true
                        },
                        "linked_content": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string"
                            },
                            "title": {
                              "type": "string"
                            }
                          }
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      },
      "put": {
        "operationId": "updateBrief",
        "summary": "Update brief",
        "description": "Update brief metadata and/or set a custom outline. To set a custom outline, include the `outline` array. To update only metadata (topic, keywords, etc.), omit `outline`. Cannot update outline while brief generation is in progress (status='pending', 'generating', or 'research').",
        "tags": [
          "Briefs"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "topic": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "target_keywords": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "content_type": {
                    "type": "string",
                    "enum": [
                      "blog",
                      "guide",
                      "landing",
                      "product",
                      "comparison",
                      "listicle"
                    ]
                  },
                  "search_intent": {
                    "type": "string",
                    "description": "Search intent classification",
                    "enum": [
                      "informational",
                      "navigational",
                      "transactional",
                      "commercial"
                    ]
                  },
                  "target_word_count": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "outline": {
                    "type": "array",
                    "description": "Custom content outline sections. When provided, replaces the entire outline. Each section defines a heading for content generation.",
                    "minItems": 1,
                    "maxItems": 50,
                    "items": {
                      "$ref": "#/components/schemas/ContentOutlineSection"
                    }
                  },
                  "variation_overrides": {
                    "type": "object",
                    "description": "Override content variation parameters (tone, voice, angle).",
                    "properties": {
                      "tone": {
                        "type": "string",
                        "description": "Writing tone (e.g. 'professional', 'conversational')"
                      },
                      "voice_persona": {
                        "type": "string",
                        "description": "Voice persona for content generation"
                      },
                      "angle": {
                        "type": "string",
                        "description": "Content angle or perspective"
                      }
                    }
                  },
                  "audience_context": {
                    "type": "object",
                    "description": "Target audience context for content generation.",
                    "properties": {
                      "role": {
                        "type": "string"
                      },
                      "expertise": {
                        "type": "string",
                        "enum": [
                          "beginner",
                          "intermediate",
                          "expert"
                        ]
                      },
                      "pain_point": {
                        "type": "string"
                      },
                      "funnel_stage": {
                        "type": "string",
                        "enum": [
                          "awareness",
                          "consideration",
                          "decision"
                        ]
                      }
                    }
                  },
                  "topic_guardrails": {
                    "type": "object",
                    "description": "Topic guardrails for content generation.",
                    "required": [
                      "required",
                      "excluded"
                    ],
                    "properties": {
                      "required": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Topics that must be covered"
                      },
                      "excluded": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Topics to avoid"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Brief updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "topic": {
                          "type": "string"
                        },
                        "target_keywords": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "content_type": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "outline_section_count": {
                          "type": "integer",
                          "description": "Returned when outline is updated"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/briefs/{id}/status": {
      "get": {
        "operationId": "getBriefStatus",
        "summary": "Get brief generation status",
        "description": "Check the status of brief research and generation.",
        "tags": [
          "Briefs"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Brief status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "topic": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "is_processing": {
                          "type": "boolean"
                        },
                        "is_complete": {
                          "type": "boolean"
                        },
                        "is_failed": {
                          "type": "boolean"
                        },
                        "progress": {
                          "type": "object",
                          "properties": {
                            "current_step": {
                              "type": "string"
                            },
                            "completed_steps": {
                              "type": "integer"
                            },
                            "total_steps": {
                              "type": "integer"
                            },
                            "percent_complete": {
                              "type": "integer"
                            }
                          }
                        },
                        "error": {
                          "type": "string",
                          "nullable": true
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/briefs/{id}/facts": {
      "get": {
        "operationId": "listBriefFacts",
        "summary": "List a brief's fact ledger",
        "description": "Every claim recorded for this brief, with its provenance, verification and approval. Ordered pending-first, then by provenance, then by creation. A brief with no facts is a 200 with an empty list, not a 404 — the ledger simply has not minted yet.",
        "tags": [
          "Briefs"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The brief's facts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "facts": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Fact"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "operationId": "contributeBriefFacts",
        "summary": "Contribute claims, sources, or both to a brief's fact ledger",
        "description": "Records what only the customer knows. Each entry is either a claim they are asserting (stored as theirs and cited to them) or a URL alone, which is fetched so its claims can be extracted. A claim may also carry `source_url`: the page the caller says backs that claim, attached in the SAME write and recorded as the caller's own decision (`human_verified`), never as machine grounding. A claim and its `source_url` land together or not at all, so no result ever means \"the fact saved but its source did not\" \u2014 such an entry comes back `failed`. Reported per contribution: a body of three where one is rejected is a 200 naming that one with its reason, not a 400 discarding the other two.",
        "tags": ["Briefs"],
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["contributions"],
                "properties": {
                  "contributions": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 3,
                    "items": {
                      "type": "object",
                      "required": ["kind", "text"],
                      "properties": {
                        "kind": {
                          "type": "string",
                          "enum": ["figure", "source", "experience"]
                        },
                        "text": {
                          "type": "string",
                          "description": "The customer's own words. A full http(s) URL on its own is fetched and its claims extracted; anything else is stored as their own claim."
                        },
                        "source_url": {
                          "type": "string",
                          "format": "uri",
                          "description": "Optional. A page backing this claim, attached to it and cited to the caller. This does NOT fetch the page for claims \u2014 put a URL alone in `text` for that. Ignored when `text` is itself a URL."
                        }
                      }
                    }
                  },
                  "split_multi_item": {
                    "type": "boolean",
                    "description": "Split one entry's text into several facts when it lists separate claims. One contribution can then produce several results, so do not assume the results array matches the input by index."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Per-contribution results. `status` is written | already_existed | queued | failed. On a success, `source_url` echoes back only when the source was actually attached, and `source_skipped` says why when a URL was sent and deliberately not attached."
          },
          "400": { "$ref": "#/components/responses/ValidationError" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/briefs/{id}/sources": {
      "post": {
        "operationId": "setBriefSourceDecision",
        "summary": "Verify, replace, or remove one fact source",
        "description": "Records a durable decision about one claim/source pair. `human_verified` vouches for the page; `removed` removes only the link and keeps the claim. To replace a source, send its `decision_url` from GET /briefs/{id}/facts as `source_url` and the new page as `replacement_url`. The server also resolves a currently displayed replacement URL back to its durable key when unambiguous.",
        "tags": ["Briefs"],
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["claim", "source_url", "decision"],
                "properties": {
                  "claim": {
                    "type": "string",
                    "description": "The exact claim text returned by the fact ledger."
                  },
                  "source_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The source's `decision_url`, or its visible `url` when no decision_url is present."
                  },
                  "replacement_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The new page replacing source_url. Allowed only with human_verified."
                  },
                  "decision": {
                    "type": "string",
                    "enum": ["human_verified", "removed"]
                  },
                  "quote": {
                    "type": "string",
                    "description": "An optional exact supporting sentence from the page."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The recorded decision and its durable decision_url."
          },
          "400": { "$ref": "#/components/responses/ValidationError" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/briefs/{id}/facts/{factId}": {
      "patch": {
        "operationId": "setBriefFactApproval",
        "summary": "Approve or reject one fact",
        "description": "Approving a claim lets generation state it and require it through a rewrite; rejecting excludes it permanently — no later research run or replay can hand a rejected claim back. `expected_updated_at` is required and must be the exact `updated_at` you read for this fact; literal null is rejected, because a fact row is stamped at mint and can never have a null timestamp.",
        "tags": [
          "Briefs"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "factId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "approval",
                  "expected_updated_at"
                ],
                "properties": {
                  "approval": {
                    "type": "string",
                    "enum": [
                      "approved",
                      "rejected"
                    ]
                  },
                  "expected_updated_at": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated fact, carrying its rotated `updated_at`",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "fact": {
                          "$ref": "#/components/schemas/Fact"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The fact changed since you read it. Re-read and retry with the current `updated_at`."
          }
        }
      }
    },
    "/briefs/{id}/sections/{sectionNumber}": {
      "patch": {
        "operationId": "updateBriefSection",
        "summary": "Update one section of a brief's outline",
        "description": "Partial update of a single section. Omitted fields keep their value; `null` clears `owned_keywords` only. `expected_updated_at` is required and is the whole BRIEF's `updated_at` from GET /briefs/{id} — pass literal null if that read returned null. Send `expected_heading` to assert which section you believe number N is; the write is refused if the outline was reordered under you.\n\nA brief that was imported carries its structure as an outline and no content plan. Editing one of its sections materialises the plan on first write and persists both projections, so no plan needs to exist first. A brief with neither a plan nor an outline is refused.",
        "tags": [
          "Briefs"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "sectionNumber",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "1-based position in the outline."
          },
          {
            "name": "dry_run",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true"
              ]
            },
            "description": "Pass `true` to return the patch that WOULD be applied and write nothing — the confirmation step a caller with no UI cannot otherwise see. The body is still validated, so a dry run cannot accept what the real call would reject. Echoes the request rather than simulating the merge: the merge lives in the writer, and a second implementation of it here would be free to drift."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "expected_updated_at"
                ],
                "description": "At least one patchable field must be present.",
                "properties": {
                  "expected_updated_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  },
                  "expected_heading": {
                    "type": "string"
                  },
                  "heading": {
                    "type": "string"
                  },
                  "key_points": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "suggested_word_count": {
                    "type": "integer"
                  },
                  "description": {
                    "type": "string"
                  },
                  "format_instructions": {
                    "type": "string"
                  },
                  "owned_keywords": {
                    "type": "array",
                    "nullable": true,
                    "items": {
                      "type": "string"
                    }
                  },
                  "assigned_to": {
                    "type": "string",
                    "enum": [
                      "ai",
                      "user"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated section and the brief's new `updated_at`",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "section_number": {
                          "type": "integer"
                        },
                        "section": {
                          "$ref": "#/components/schemas/BriefSection"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "One of: the brief changed since you read it (`conflict`); section N is no longer the heading you asserted (`stale_section_heading`); or the brief is generating (`generation_in_progress`)."
          }
        }
      }
    },
    "/briefs/{id}/export": {
      "get": {
        "operationId": "exportBrief",
        "summary": "Export brief",
        "description": "Export brief in JSON or Markdown format.",
        "tags": [
          "Briefs"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "markdown"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Exported brief",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "topic": {
                          "type": "string"
                        },
                        "target_keywords": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "content_type": {
                          "type": "string"
                        },
                        "target_word_count": {
                          "type": "integer"
                        },
                        "outline": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ContentOutlineSection"
                          }
                        },
                        "competitor_urls": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "notes": {
                          "type": "string",
                          "nullable": true
                        },
                        "questions_to_answer": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "unique_angle": {
                          "type": "string",
                          "nullable": true
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "export_format": {
                          "type": "string"
                        },
                        "exported_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/research": {
      "get": {
        "operationId": "listResearch",
        "summary": "List research",
        "description": "Retrieve all research sessions in your organization.",
        "tags": [
          "Research"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter research sessions by site ID"
          },
          {
            "name": "briefable",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false",
                "1",
                "0"
              ]
            },
            "description": "true restricts the list to sessions POST /briefs will accept right now (finished agent sessions; excludes archived sessions and legacy/migrated research whose ids the brief endpoint cannot resolve or whose status is untrustworthy). Build brief-creation pickers from this filter — an id from the unfiltered list can be a guaranteed 404 or 422. Any other value is a 400."
          }
        ],
        "responses": {
          "200": {
            "description": "List of research sessions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedResearch"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "operationId": "startResearch",
        "summary": "Start research",
        "description": "Start AI-powered research on a topic. Research runs asynchronously — use the returned session ID with GET /research/{id} to check progress. The research_url field provides a direct link to view the research in the Frase app.",
        "tags": [
          "Research"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query",
                  "site_id"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 500,
                    "description": "The topic or search query to research"
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "The site to associate the research with (required). Provides brand context, language, and country defaults."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "general",
                      "topic",
                      "competitor",
                      "gap"
                    ],
                    "default": "general",
                    "description": "Research type. 'general' runs keywords + SERP + gaps + evidence + AI visibility. 'topic' maps subtopic directions. 'competitor' and 'gap' run the general pipeline with type-specific strategy context."
                  },
                  "language": {
                    "type": "string",
                    "description": "Language code (e.g., 'en'). Falls back to site language if omitted."
                  },
                  "country": {
                    "type": "string",
                    "description": "Country code (e.g., 'US'). Falls back to site country if omitted."
                  },
                  "competitor_domains": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Competitor domains to analyze (used with type=competitor or type=gap)"
                  },
                  "audience": {
                    "type": "string",
                    "description": "Target audience context for research"
                  },
                  "objective": {
                    "type": "string",
                    "description": "Content objective — what the research should accomplish"
                  },
                  "focus": {
                    "type": "string",
                    "description": "Focus area or differentiation lens"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Research started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "query": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "nullable": true
                        },
                        "language": {
                          "type": "string",
                          "nullable": true
                        },
                        "country": {
                          "type": "string",
                          "nullable": true
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "research_url": {
                          "type": "string",
                          "description": "URL to view the research session in the Frase app"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/research/{id}": {
      "get": {
        "operationId": "getResearch",
        "summary": "Get research",
        "description": "Retrieve a specific research session by ID.",
        "tags": [
          "Research"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Research details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Research"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "operationId": "deleteResearch",
        "summary": "Delete research",
        "description": "Soft delete a research session (moves to trash).",
        "tags": [
          "Research"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Research deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/research/{id}/export": {
      "get": {
        "operationId": "exportResearch",
        "summary": "Export research",
        "description": "Export research findings in JSON or Markdown format.",
        "tags": [
          "Research"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "markdown"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Exported research",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchExport"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/audits": {
      "get": {
        "operationId": "listAudits",
        "summary": "List audits",
        "description": "Retrieve all site audits.",
        "tags": [
          "Audits"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "crawling",
                "analyzing",
                "completed",
                "failed"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of audits",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string",
                            "nullable": true
                          },
                          "type": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "progress": {
                            "type": "integer",
                            "nullable": true
                          },
                          "pages_audited": {
                            "type": "integer"
                          },
                          "total_issues": {
                            "type": "integer"
                          },
                          "critical_issues": {
                            "type": "integer"
                          },
                          "overall_score": {
                            "type": "integer",
                            "nullable": true
                          },
                          "site": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "domain": {
                                "type": "string"
                              }
                            }
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "completed_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "startAudit",
        "summary": "Start audit",
        "description": "Start a new site audit.",
        "tags": [
          "Audits"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string",
                    "description": "Custom audit name"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "full",
                      "quick",
                      "technical"
                    ]
                  },
                  "max_pages": {
                    "type": "integer",
                    "description": "Maximum pages to crawl"
                  },
                  "selected_page_urls": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Specific URLs to audit"
                  },
                  "settings": {
                    "type": "object",
                    "description": "Advanced audit settings"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Audit started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string",
                          "nullable": true
                        },
                        "type": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "site": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            },
                            "domain": {
                              "type": "string"
                            }
                          }
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/audits/{id}": {
      "get": {
        "operationId": "getAudit",
        "summary": "Get audit",
        "description": "Retrieve audit details and summary.",
        "tags": [
          "Audits"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "include_pages",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Include audited pages in response"
          },
          {
            "name": "page_limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            },
            "description": "Max pages to include (when include_pages=true)"
          }
        ],
        "responses": {
          "200": {
            "description": "Audit details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string",
                          "nullable": true
                        },
                        "type": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "progress": {
                          "type": "integer",
                          "nullable": true
                        },
                        "pages_audited": {
                          "type": "integer",
                          "nullable": true
                        },
                        "total_issues": {
                          "type": "integer",
                          "nullable": true
                        },
                        "critical_issues": {
                          "type": "integer",
                          "nullable": true
                        },
                        "overall_score": {
                          "type": "integer",
                          "nullable": true
                        },
                        "summary": {
                          "type": "object",
                          "nullable": true
                        },
                        "cannibalization": {
                          "type": "array",
                          "nullable": true,
                          "description": "Keyword-cannibalization groups from this audit. Null until the cannibalization pass has run. Each group carries the keyword and the competing pages; see GET /site-health/cannibalization for the same data with a stable per-group shape.",
                          "items": {
                            "type": "object"
                          }
                        },
                        "internal_link_graph": {
                          "type": "object",
                          "nullable": true,
                          "description": "The crawl's internal link graph as stored by the audit pipeline. Null until the link-graph pass has run. Per-page link facts are on pages[] (internal_page_rank, internal_links_in/out, click_depth, is_orphan, is_dead_end); this object is the raw graph behind them.",
                          "properties": {}
                        },
                        "site": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string",
                              "nullable": true
                            },
                            "domain": {
                              "type": "string"
                            }
                          }
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "completed_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "pages": {
                          "type": "array",
                          "nullable": true,
                          "description": "Included when include_pages=true",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "url": {
                                "type": "string"
                              },
                              "title": {
                                "type": "string",
                                "nullable": true
                              },
                              "status_code": {
                                "type": "integer",
                                "nullable": true,
                                "description": "Final HTTP status of the fetch, after redirects. Recorded on crawler-discovered pages AND on manually scoped (selected-URL) audits; null only where no status was captured, which is not evidence the page was reachable. A row with status_code >= 400 is a dead-page tombstone rather than a page: it is excluded, carries no score and no issues, and exists only so the site view can retire the URL. Dead URLs that other pages still link to also surface as broken_link issues on the linking page; unlinked ones surface in the app as a single site-wide dead_page finding, which no v1 endpoint emits today."
                              },
                              "score": {
                                "type": "integer",
                                "nullable": true,
                                "description": "Canonical page-v2 score: the equal mean of E-E-A-T, SEO and GEO. The same formula is used by crawl, API and synchronous single-page audits. Null when any required pillar is unmeasured — never replaced by a different formula. Formula version and coverage are recorded in analysis_provenance.score."
                              },
                              "issues": {
                                "type": "array",
                                "items": {
                                  "type": "object"
                                }
                              },
                              "word_count": {
                                "type": "integer",
                                "nullable": true
                              },
                              "aeo_score": {
                                "type": "integer",
                                "nullable": true,
                                "description": "Answer-engine optimization score, 0-100."
                              },
                              "technical_score": {
                                "type": "integer",
                                "nullable": true,
                                "minimum": 0,
                                "maximum": 100,
                                "description": "Derived from indexability directives, canonical, head metadata, social/viewport tags, structured data, image alt text and broken internal links. Uses the authoritative stored projection when present; for historical rows where that projection is absent, derives the same score at read time from evidence already stored on the row without modifying it. This endpoint and GET /site-health therefore report the same number for the same page. Null when no technical check could run at all — the fetch was unreliable, or no head was parsed and no head-independent check found anything — which is not the same as 0. A page whose head was never parsed is scored on the checks that never needed one (title, meta description, H1 structure, image alt text, broken links) rather than dropped. Does not include page speed or internal-link authority — see internal_page_rank for the latter. Additive: this field is new in this response, so no existing consumer loses a value. Guard for null before arithmetic."
                              },
                              "internal_page_rank": {
                                "type": "integer",
                                "nullable": true,
                                "minimum": 0,
                                "maximum": 100,
                                "description": "PageRank over the site's internal link graph, min-max normalized across the crawled set, so it is not comparable between runs of different sizes."
                              },
                              "internal_links_in": {
                                "type": "integer",
                                "nullable": true
                              },
                              "internal_links_out": {
                                "type": "integer",
                                "nullable": true
                              },
                              "click_depth": {
                                "type": "integer",
                                "nullable": true,
                                "description": "Clicks from the site root. null = not measured (the crawl contained no site root). -1 = measured and unreachable. >= 0 = depth."
                              },
                              "is_orphan": {
                                "type": "boolean",
                                "nullable": true,
                                "description": "null = the link graph was not measured; false genuinely means the page is not an orphan."
                              },
                              "is_dead_end": {
                                "type": "boolean",
                                "nullable": true,
                                "description": "null = the link graph was not measured; false genuinely means the page is not a dead end."
                              },
                              "eeat_score": {
                                "type": "integer",
                                "nullable": true
                              },
                              "geo_score": {
                                "type": "integer",
                                "nullable": true
                              },
                              "seo_score": {
                                "type": "integer",
                                "nullable": true
                              },
                              "agent_readiness_score": {
                                "type": "integer",
                                "nullable": true,
                                "description": "Null on pages audited before agent-readiness probing existed."
                              },
                              "agent_readiness_breakdown": {
                                "type": "object",
                                "nullable": true
                              },
                              "scoring_version": {
                                "type": "string",
                                "nullable": true
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/audits/{id}/export": {
      "get": {
        "operationId": "exportAudit",
        "summary": "Export audit",
        "description": "Export audit report in JSON or CSV format.",
        "tags": [
          "Audits"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Exported audit",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "site_id": {
                          "type": "string",
                          "nullable": true
                        },
                        "site_domain": {
                          "type": "string",
                          "nullable": true
                        },
                        "type": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "summary": {
                          "type": "object",
                          "properties": {
                            "total_pages": {
                              "type": "integer"
                            },
                            "crawled_pages": {
                              "type": "integer"
                            },
                            "avg_word_count": {
                              "type": "number"
                            },
                            "total_issues": {
                              "type": "integer"
                            },
                            "critical_issues": {
                              "type": "integer"
                            },
                            "warning_issues": {
                              "type": "integer"
                            }
                          }
                        },
                        "pages": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "completed_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "export_format": {
                          "type": "string"
                        },
                        "exported_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/audits/page": {
      "post": {
        "operationId": "auditPage",
        "summary": "Audit a single page",
        "description": "Synchronously scrape and audit a single URL, returning E-E-A-T, GEO, and SEO scores along with detected issues. Every route uses the canonical page scorer; no background audit job is queued.",
        "tags": [
          "Audits"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The URL to audit. Must be http or https."
                  },
                  "keyword": {
                    "type": "string",
                    "description": "Optional target keyword for SEO scoring context."
                  },
                  "audit_page_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional audit page ID. When provided, re-audits the page within its site audit context, updating the auditPages row and recalculating the parent audit score."
                  },
                  "site_audit_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional site audit ID. Used together with audit_page_id to specify which site audit the page belongs to."
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional site ID. When provided, the endpoint uses this site for routing instead of auto-detecting by domain."
                  },
                  "confirm_target_keyword_change": {
                    "type": "boolean",
                    "description": "Retry with true only after the user explicitly confirms replacing the page's canonical target keyword following a 409 response."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Audit completed successfully (synchronous). Returned for routes: standalone, reaudit_in_site_audit, add_to_site_audit.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "route": {
                      "type": "string",
                      "enum": [
                        "standalone",
                        "reaudit_in_site_audit",
                        "add_to_site_audit"
                      ],
                      "description": "The routing path taken by the endpoint."
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "completed",
                        "failed"
                      ]
                    },
                    "keyword": {
                      "type": "string",
                      "nullable": true
                    },
                    "content_type": {
                      "type": "string",
                      "nullable": true,
                      "description": "Canonical content type. Null when classification is not applicable or unmeasured.",
                      "enum": [
                        "blog_post",
                        "page",
                        "faq",
                        "glossary",
                        "comparison",
                        "pillar",
                        "how_to",
                        "landing",
                        "listicle",
                        "case_study",
                        "tutorial",
                        "news",
                        "product_update",
                        "data_report",
                        "event",
                        "resource",
                        "alternative",
                        "tool_review",
                        null
                      ]
                    },
                    "content_type_confidence": {
                      "type": "string",
                      "nullable": true,
                      "description": "Categorical confidence in the canonical content classification.",
                      "enum": [
                        "high",
                        "medium",
                        "low",
                        null
                      ]
                    },
                    "content_type_status": {
                      "type": "string",
                      "description": "Whether canonical classification succeeded, used a deterministic fallback, was not applicable, or was unmeasured.",
                      "enum": [
                        "classified",
                        "fallback",
                        "not_applicable",
                        "unmeasured"
                      ]
                    },
                    "content_type_method": {
                      "type": "string",
                      "nullable": true,
                      "description": "Classification method. Null when no classifier ran.",
                      "enum": [
                        "llm",
                        "deterministic",
                        null
                      ]
                    },
                    "content_type_version": {
                      "type": "string",
                      "nullable": true,
                      "description": "Internal classifier revision. Null when no classifier ran."
                    },
                    "title": {
                      "type": "string",
                      "nullable": true
                    },
                    "meta_description": {
                      "type": "string",
                      "nullable": true
                    },
                    "word_count": {
                      "type": "integer"
                    },
                    "overall_score": {
                      "type": "integer",
                      "nullable": true,
                      "minimum": 0,
                      "maximum": 100
                    },
                    "eeat_score": {
                      "type": "integer",
                      "nullable": true,
                      "minimum": 0,
                      "maximum": 100
                    },
                    "eeat_breakdown": {
                      "type": "object",
                      "nullable": true
                    },
                    "geo_score": {
                      "type": "integer",
                      "nullable": true,
                      "minimum": 0,
                      "maximum": 100
                    },
                    "geo_breakdown": {
                      "type": "object",
                      "nullable": true
                    },
                    "seo_score": {
                      "type": "integer",
                      "nullable": true,
                      "minimum": 0,
                      "maximum": 100
                    },
                    "seo_breakdown": {
                      "type": "object",
                      "nullable": true
                    },
                    "issues": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "headings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "level": {
                            "type": "integer"
                          },
                          "text": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "outbound_links": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "author_name": {
                      "type": "string",
                      "nullable": true
                    },
                    "analyzed_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Target keyword conflict. Confirm the change with the user, then retry with confirm_target_keyword_change=true."
          },
          "422": {
            "description": "Invalid URL"
          },
          "429": {
            "description": "Audit page limit exceeded"
          }
        }
      }
    },
    "/site-health": {
      "get": {
        "operationId": "getSiteHealth",
        "summary": "Get site health",
        "description": "Per-site health rollup derived from the site's most recent audit, merged with sitemap-discovered pages that have never been audited. Pages that were never audited appear with is_audited=false and null scores.",
        "tags": [
          "Site Health"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The site to report on."
          }
        ],
        "responses": {
          "200": {
            "description": "Site health overview",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "site": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "name": {
                              "type": "string"
                            },
                            "domain": {
                              "type": "string"
                            },
                            "last_audit_at": {
                              "type": "string",
                              "format": "date-time",
                              "nullable": true
                            },
                            "last_audit_score": {
                              "type": "integer",
                              "nullable": true
                            }
                          }
                        },
                        "audit_summary": {
                          "type": "string",
                          "nullable": true,
                          "description": "The audit's stored summary text. Null when the site has never been audited or the run produced none."
                        },
                        "audit_stats": {
                          "type": "object",
                          "nullable": true,
                          "description": "Null when the site has never been audited.",
                          "properties": {
                            "overall_score": {
                              "type": "integer",
                              "nullable": true
                            },
                            "pages_audited": {
                              "type": "integer",
                              "nullable": true
                            },
                            "critical_issues": {
                              "type": "integer",
                              "nullable": true
                            },
                            "warning_issues": {
                              "type": "integer",
                              "nullable": true
                            },
                            "total_issues": {
                              "type": "integer",
                              "nullable": true
                            },
                            "score_delta": {
                              "type": "integer",
                              "nullable": true
                            },
                            "ai_visibility_score": {
                              "type": "integer",
                              "nullable": true
                            }
                          }
                        },
                        "pages": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "url": {
                                "type": "string"
                              },
                              "path": {
                                "type": "string"
                              },
                              "title": {
                                "type": "string",
                                "description": "Falls back to the page path when the crawl recorded no title, so it is always a string here — unlike pages[].title on GET /audits/{id}, which is the raw column and can be null."
                              },
                              "is_homepage": {
                                "type": "boolean"
                              },
                              "is_audited": {
                                "type": "boolean",
                                "description": "False for a page discovered from the sitemap but never audited. Its scores are null."
                              },
                              "last_audit": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              },
                              "issues_count": {
                                "type": "integer"
                              },
                              "score": {
                                "type": "integer",
                                "nullable": true,
                                "minimum": 0,
                                "maximum": 100,
                                "description": "The latest canonical score for this site and URL. Null means the required score inputs were not all measured."
                              },
                              "score_basis_version": {
                                "type": "string",
                                "nullable": true,
                                "description": "page-v2 for current rows. Historical rows may report their legacy basis."
                              },
                              "score_coverage": {
                                "type": "object",
                                "nullable": true,
                                "description": "Coverage recorded by page-v2. Null on historical rows that predate coverage metadata.",
                                "properties": {
                                  "required": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  },
                                  "measured": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  },
                                  "missing": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  },
                                  "complete": {
                                    "type": "boolean"
                                  }
                                }
                              },
                              "technical_score": {
                                "type": "integer",
                                "nullable": true,
                                "minimum": 0,
                                "maximum": 100,
                                "description": "Derived from indexability directives, canonical, head metadata, social/viewport tags, structured data, image alt text and broken internal links. Uses the authoritative stored projection when present; for historical rows where that projection is absent, derives the same score at read time from evidence already stored on the row without modifying it. This endpoint and GET /audits/{id} therefore report the same number for the same page. Null when no technical check could run at all — the fetch was unreliable, or no head was parsed and no head-independent check found anything — which is not the same as 0. Does not include page speed or internal-link authority. BREAKING CHANGE: on an audited page this was previously always an integer, computed as 100 minus 10 per issue the display taxonomy called technical, so a page nobody could read scored a confident number. It is now null in exactly those cases (it was already null on a never-audited page, where is_audited is false). Guard for null before arithmetic."
                              },
                              "content_score": {
                                "type": "integer",
                                "nullable": true
                              },
                              "aeo_score": {
                                "type": "integer",
                                "nullable": true
                              },
                              "is_tracked": {
                                "type": "boolean"
                              },
                              "authority_score": {
                                "type": "integer",
                                "nullable": true,
                                "description": "PageRank over the site's internal link graph, min-max normalized across the crawled set, so it is not comparable between runs of different sizes."
                              },
                              "is_orphan": {
                                "type": "boolean",
                                "nullable": true,
                                "description": "null = the link graph was not measured; false genuinely means the page is not an orphan."
                              },
                              "is_dead_end": {
                                "type": "boolean",
                                "nullable": true,
                                "description": "null = the link graph was not measured; false genuinely means the page is not a dead end."
                              },
                              "click_depth": {
                                "type": "integer",
                                "nullable": true,
                                "description": "Clicks from the site root. null = not measured (the crawl contained no site root). -1 = measured and unreachable. >= 0 = depth."
                              },
                              "internal_links_in": {
                                "type": "integer",
                                "nullable": true
                              },
                              "internal_links_out": {
                                "type": "integer",
                                "nullable": true
                              },
                              "link_metrics_scope": {
                                "type": "string",
                                "enum": [
                                  "site",
                                  "run",
                                  "unknown"
                                ],
                                "nullable": true,
                                "description": "Which node set this page's link metrics were measured over. \"site\" = the site-wide internal-link count named by authority_summary.link_metrics_measured_at; \"run\" = this page was audited AFTER that count, so its is_orphan / is_dead_end are withheld (null) rather than reported against a set they were never measured on; \"unknown\" = the site has never been counted site-wide, and the values are exactly what they always were. Without this field, is_orphan: null carries both meanings with nothing to tell them apart. Additive."
                              },
                              "word_count": {
                                "type": "integer",
                                "nullable": true
                              }
                            }
                          }
                        },
                        "average_scores": {
                          "type": "object",
                          "properties": {
                            "technical": {
                              "type": "integer",
                              "nullable": true,
                              "minimum": 0,
                              "maximum": 100,
                              "description": "Null when no page in the resolved set had a readable technical measurement — including a site that has never been audited. BREAKING CHANGE: this was previously always an integer and returned 0 in exactly those cases, so a never-measured site was indistinguishable from a site scoring 0. Guard for null before arithmetic."
                            },
                            "content": {
                              "type": "integer",
                              "description": "0 when no page had a content measurement. Unchanged."
                            },
                            "aeo": {
                              "type": "integer",
                              "description": "0 when no page had an AEO measurement. Unchanged."
                            }
                          }
                        },
                        "issue_summary": {
                          "type": "object"
                        },
                        "last_audit_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true
                        },
                        "authority_summary": {
                          "type": "object",
                          "nullable": true,
                          "description": "Null when the site has no link-graph data.",
                          "properties": {
                            "average_authority_score": {
                              "type": "integer",
                              "description": "Mean authority over the pages that carry one. Always a number when authority_summary itself is present — the object is only emitted once at least one page has an authority score."
                            },
                            "links_measured": {
                              "type": "boolean",
                              "description": "Whether the internal link graph's EDGES were measured. Keyed on is_orphan / is_dead_end, which are derived from the extracted internal links alone and need no site root. False when the crawl extracted no edges at all, in which case orphan_pages_count and dead_end_pages_count are absences rather than zeros."
                            },
                            "depth_measured": {
                              "type": "boolean",
                              "description": "Whether click depth was measured. Keyed on click_depth ONLY, because it is the sole traversal column that is genuinely NULL when unmeasured (is_orphan carries a schema DEFAULT of false, so no null-check on it can detect an unwalked graph). False when the crawl contained no site root to run the breadth-first walk from — every manually scoped audit is in that state — in which case deep_pages_count is an absence rather than a zero. Independent of links_measured: a scoped audit is routinely links_measured=true, depth_measured=false."
                            },
                            "link_metrics_scope": {
                              "type": "string",
                              "enum": [
                                "site",
                                "run",
                                "mixed",
                                "unknown"
                              ],
                              "description": "Which page set orphan_pages_count and dead_end_pages_count were measured over. \"mixed\" is the ordinary state in the window after a crawl: some pages were audited since the last site-wide count and are NOT included in the two counts — a boolean cannot express that, which is how a half-counted site published a confident 0. \"unknown\" = never counted site-wide; nothing is withheld. Additive."
                            },
                            "link_graph_node_count": {
                              "type": "integer",
                              "nullable": true,
                              "description": "URLs in the site-wide link graph. A NODE count — one node per normalized URL — NOT a page count: it sits below the audited-row count wherever query-string variants collapsed onto one node, and it counts excluded rows that pages[] omits. Comparing it with pages.length is a category error. null = never counted. Additive."
                            },
                            "link_metrics_measured_at": {
                              "type": "string",
                              "format": "date-time",
                              "nullable": true,
                              "description": "When that site-wide count was taken. null = never counted. Additive."
                            },
                            "orphan_pages_count": {
                              "type": "integer",
                              "description": "Pages with no inbound internal link. 0 when links_measured is false means 'not measured', not 'no orphans'."
                            },
                            "dead_end_pages_count": {
                              "type": "integer",
                              "description": "Pages with no outbound internal link. Read together with links_measured."
                            },
                            "deep_pages_count": {
                              "type": "integer",
                              "description": "Pages further than the depth threshold from the site root. Read together with depth_measured — depth is the one figure here that needs a root, so this is the count most often 0-by-absence."
                            },
                            "top_authority_pages": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "url": {
                                    "type": "string"
                                  },
                                  "title": {
                                    "type": "string",
                                    "description": "Falls back to the page path, so never null."
                                  },
                                  "authority_score": {
                                    "type": "integer"
                                  },
                                  "internal_links_in": {
                                    "type": "integer"
                                  },
                                  "internal_links_out": {
                                    "type": "integer"
                                  }
                                }
                              }
                            }
                          }
                        },
                        "has_gsc": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "site_id is missing or not a valid UUID."
          },
          "404": {
            "description": "Site not found in this organization."
          }
        }
      }
    },
    "/site-health/links": {
      "get": {
        "operationId": "getSiteHealthLinks",
        "summary": "Get internal link data",
        "description": "Internal-link facts from the latest completed audit, in one of two modes decided by which query parameter you send. Pass page_id for one page's inbound and outbound internal links. Pass site_id (and no page_id) for a site-level summary of orphans, dead ends and top-authority pages. The two modes return DIFFERENT payload shapes — see the response schema's oneOf. If both are sent, page_id wins.",
        "tags": [
          "Site Health"
        ],
        "parameters": [
          {
            "name": "page_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "A page from the pages[] of GET /audits/{id}. Selects the per-page mode."
          },
          {
            "name": "site_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Selects the site-level summary mode, resolved against the site's latest completed audit. Ignored when page_id is present."
          }
        ],
        "responses": {
          "200": {
            "description": "Per-page links (page_id mode) or the site-level link summary (site_id mode).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "oneOf": [
                        {
                          "type": "object",
                          "title": "Per-page links (page_id mode)",
                          "description": "Keys are camelCase here, unlike the snake_case used elsewhere in this API — that is the shape the endpoint has always returned and it is not changing.",
                          "properties": {
                            "linksIn": {
                              "type": "array",
                              "description": "Other pages of the same crawl that link TO this page.",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "url": {
                                    "type": "string"
                                  },
                                  "path": {
                                    "type": "string"
                                  },
                                  "title": {
                                    "type": "string"
                                  },
                                  "isNavigation": {
                                    "type": "boolean",
                                    "description": "True when the link was found in site chrome (nav, header, footer) rather than in the body. Absent when unknown."
                                  }
                                }
                              }
                            },
                            "linksOut": {
                              "type": "array",
                              "description": "Pages of the same crawl this page links to.",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "url": {
                                    "type": "string"
                                  },
                                  "path": {
                                    "type": "string"
                                  },
                                  "title": {
                                    "type": "string"
                                  },
                                  "isNavigation": {
                                    "type": "boolean"
                                  }
                                }
                              }
                            }
                          }
                        },
                        {
                          "type": "object",
                          "title": "Site-level summary (site_id mode)",
                          "properties": {
                            "audit_id": {
                              "type": "string",
                              "format": "uuid",
                              "description": "The latest completed audit this summary was drawn from."
                            },
                            "total_pages": {
                              "type": "integer"
                            },
                            "links_measured": {
                              "type": "boolean",
                              "description": "Whether the internal link graph's EDGES were measured. Keyed on is_orphan / is_dead_end, which need no site root. False when the crawl extracted no edges, in which case the two lists below mean 'not measured' rather than 'none found'."
                            },
                            "depth_measured": {
                              "type": "boolean",
                              "description": "Whether click depth was measured. Keyed on click_depth ONLY — the sole traversal column that is genuinely NULL when unmeasured (is_orphan defaults to false in the schema). False when the crawl contained no site root to walk from. This payload publishes no depth figure; the flag reports whether the audit has one at all."
                            },
                            "link_metrics_scope": {
                              "type": "string",
                              "enum": [
                                "site",
                                "run",
                                "mixed",
                                "unknown"
                              ],
                              "description": "Which node set the two lists below were measured over. This payload reads ONE audit's rows, while the link columns are written by a site-wide count over the site's resolved page set — so a row speaks for the site only when it is that URL's winning row and predates the count. \"mixed\" is ordinary for an older audit whose pages have since been re-crawled; \"unknown\" = the site has never been counted and nothing is withheld. Additive."
                            },
                            "link_graph_node_count": {
                              "type": "integer",
                              "nullable": true,
                              "description": "URLs in the site-wide link graph. A NODE count — one per normalized URL — not a page count, and not comparable with total_pages. null = never counted. Additive."
                            },
                            "link_metrics_measured_at": {
                              "type": "string",
                              "format": "date-time",
                              "nullable": true,
                              "description": "When that site-wide count was taken. null = never counted. Additive."
                            },
                            "orphan_pages": {
                              "type": "array",
                              "description": "Up to 25 pages with no inbound internal link. Empty means 'none found' only when links_measured is true.",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "url": {
                                    "type": "string"
                                  },
                                  "title": {
                                    "type": "string",
                                    "description": "Empty string when the crawl recorded no title."
                                  }
                                }
                              }
                            },
                            "dead_end_pages": {
                              "type": "array",
                              "description": "Up to 25 pages with no outbound internal link. Same links_measured caveat as orphan_pages.",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "url": {
                                    "type": "string"
                                  },
                                  "title": {
                                    "type": "string"
                                  }
                                }
                              }
                            },
                            "top_authority_pages": {
                              "type": "array",
                              "description": "Up to 10 pages by authority score, descending.",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "url": {
                                    "type": "string"
                                  },
                                  "title": {
                                    "type": "string"
                                  },
                                  "authority_score": {
                                    "type": "integer"
                                  }
                                }
                              }
                            }
                          }
                        }
                      ]
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Neither page_id nor site_id was sent, or the one sent is not a valid UUID."
          },
          "404": {
            "description": "The page is not in this organization, the page has no crawl behind it (a standalone single-page result has no link graph), or the site has no completed audit."
          }
        }
      }
    },
    "/ai-visibility": {
      "get": {
        "operationId": "getAIVisibilityOverview",
        "summary": "Get AI visibility overview",
        "description": "Get an overview of your brand visibility across AI platforms.",
        "tags": [
          "AI Visibility"
        ],
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "description": "Number of days to look back (1-90)",
            "schema": {
              "type": "integer",
              "default": 30,
              "minimum": 1,
              "maximum": 90
            }
          }
        ],
        "responses": {
          "200": {
            "description": "AI visibility overview",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AIVisibilityOverview"
                }
              }
            }
          }
        }
      }
    },
    "/ai-visibility/industry-benchmark": {
      "get": {
        "operationId": "getIndustryBenchmark",
        "summary": "Get industry benchmark",
        "description": "Compare your site or organization against industry benchmarks for the resolved vertical across AI search platforms. Returns citation rates, Geo score, and share-of-voice with industry medians. Filters to a site when site_id is provided (silently ignored if site_id is not in your organization); otherwise returns the org-level aggregate. Set include_org=false for an industry-only view. Cookie/session auth is intentionally not supported.",
        "tags": [
          "AI Visibility"
        ],
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "description": "UUID of a site in your organization. Cross-org IDs are silently nulled to the org-level aggregate.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "include_org",
            "in": "query",
            "description": "Include org-specific overlay fields (orgRate, orgP50, articleCount, orgPct). When 'false', only industry-side fields are returned. Wire format is the string 'true' or 'false'.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "true"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Composite industry-benchmark payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IndustryBenchmarkPayload"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/ai-visibility/citation-formula": {
      "get": {
        "operationId": "getCitationFormula",
        "summary": "Get citation-formula coaching for the org's vertical",
        "description": "Return the top content moves that correlate with higher AI search citation rates in the caller's industry. flavor=active (default) returns a single top recommendation; flavor=full returns the ranked list of all positive correlates above the sample-size floor. Methodology fields (raw correlation coefficients, p-values, sample sizes) are intentionally absent from the wire shape. Cookie/session auth is intentionally not supported.",
        "tags": [
          "AI Visibility"
        ],
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "flavor",
            "in": "query",
            "description": "active = single top recommendation. full = ranked list of all positive moves available for your industry.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "full"
              ],
              "default": "active"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Citation-formula payload. Wire shape is single-object: when flavor=active the formulas field is null; when flavor=full the active field is null and formulas may be empty.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CitationFormulaPayload"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/ai-visibility/prompts": {
      "get": {
        "operationId": "listTrackedPrompts",
        "summary": "List tracked prompts",
        "description": "List all prompts being tracked for AI visibility.",
        "tags": [
          "AI Visibility"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "paused",
                "archived"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of tracked prompts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "prompt_text": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "frequency": {
                            "type": "string"
                          },
                          "target_brand": {
                            "type": "string"
                          },
                          "last_checked_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updated_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createTrackedPrompt",
        "summary": "Add tracked prompt",
        "description": "Add a new prompt to track for AI visibility.\n\n### 2026-10-22 - Site ownership is required\nBREAKING: site_id is now required and must name a live site owned by the API key organization. Previously omitted values created organization-wide prompts. Update integrations and MCP clients to supply a selected site UUID from list_sites; missing site_id returns HTTP 400.",
        "tags": [
          "AI Visibility"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "prompt_text",
                  "target_brand",
                  "site_id"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required site owned by the API key's organization."
                  },
                  "prompt_text": {
                    "type": "string",
                    "minLength": 10,
                    "maxLength": 1000
                  },
                  "target_brand": {
                    "type": "string",
                    "maxLength": 255
                  },
                  "brand_variants": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "frequency": {
                    "type": "string",
                    "enum": [
                      "daily",
                      "weekly",
                      "manual"
                    ]
                  },
                  "platforms": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "chatgpt",
                        "perplexity",
                        "claude",
                        "gemini",
                        "google_ai",
                        "grok",
                        "copilot",
                        "deepseek"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Prompt created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "prompt_text": {
                          "type": "string"
                        },
                        "target_brand": {
                          "type": "string"
                        },
                        "frequency": {
                          "type": "string"
                        },
                        "platforms": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "status": {
                          "type": "string"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ActivePromptLimitExceeded"
          }
        }
      }
    },
    "/ai-visibility/prompts/{id}": {
      "get": {
        "operationId": "getTrackedPrompt",
        "summary": "Get tracked prompt",
        "description": "Get details of a tracked prompt with historical results.\n\n`results` lists every check that ran for the prompt, newest first, one item per platform per night. Each item's `status` says what the check was: `scored` (an answer arrived and was read for the brand; `visibility_score` 0 means the brand was absent), `no_ai_answer` (Google showed no AI Overview for the question that night; nothing to score), `could_not_be_scored` (an answer arrived but the capture lost the evidence needed to read it), `check_failed` (the probe itself failed, or the analyzer could not read the answer and wrote no score: its analysis failed, or a platform other than Google sent back an empty answer), or `pending` (the answer has not been analyzed yet). On every status except `scored`, `mention_count`, `citation_url`, `sentiment_score` and `visibility_score` are null, never 0. A night with no item is a night no check ran.\n\n### 2026-10-27 - an answer whose analysis failed is `check_failed`\n\nBREAKING for default result sets: an answer the analyzer gave up on without writing a score (its analysis failed, or a platform other than Google sent back an empty answer) used to read `pending` with no end. It now reads `check_failed`. An answer that already holds a score stays `scored`, and a blank Google answer stays `no_ai_answer`. Clients waiting for `pending` items to resolve should stop waiting on these; a re-read of a stored non-empty answer can still turn one `scored`. No other status changes, and the enum is unchanged.\n\n### 2026-10-20 - every check is listed, with a `status`\n\nBREAKING for default result sets: `results` used to contain only scored checks, so a night Google showed no AI Overview, a night the capture could not be scored, a night the probe failed and a night no check ran all arrived as the same missing date. Every attempt is now an item with a `status`. Clients averaging `visibility_score` or `mention_count` should skip items whose `status` is not `scored` (their numbers are null) rather than counting them as misses.",
        "tags": [
          "AI Visibility"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "include_results",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "result_limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Prompt details with results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "prompt_text": {
                          "type": "string"
                        },
                        "target_brand": {
                          "type": "string"
                        },
                        "brand_variants": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "frequency": {
                          "type": "string"
                        },
                        "platforms": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "status": {
                          "type": "string"
                        },
                        "latest_visibility_score": {
                          "type": "number",
                          "nullable": true
                        },
                        "last_checked_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "results": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "platform": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "scored",
                                  "no_ai_answer",
                                  "could_not_be_scored",
                                  "check_failed",
                                  "pending"
                                ],
                                "description": "What this check was. Only `scored` carries numbers; on every other status the numeric fields are null."
                              },
                              "mention_count": {
                                "type": "integer",
                                "nullable": true
                              },
                              "citation_url": {
                                "type": "string",
                                "nullable": true
                              },
                              "response_snippet": {
                                "type": "string",
                                "nullable": true
                              },
                              "sentiment_score": {
                                "type": "number",
                                "nullable": true
                              },
                              "visibility_score": {
                                "type": "number",
                                "nullable": true
                              },
                              "checked_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateTrackedPrompt",
        "summary": "Update tracked prompt",
        "description": "Update prompt status, frequency, or platforms.",
        "tags": [
          "AI Visibility"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "paused",
                      "archived"
                    ]
                  },
                  "frequency": {
                    "type": "string",
                    "enum": [
                      "daily",
                      "weekly",
                      "manual"
                    ]
                  },
                  "platforms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "brand_variants": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Prompt updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string"
                        },
                        "frequency": {
                          "type": "string"
                        },
                        "platforms": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/ActivePromptLimitExceeded"
          }
        }
      }
    },
    "/ai-visibility/competitors": {
      "get": {
        "operationId": "getAICompetitors",
        "summary": "Get competitor analysis",
        "description": "Get competitive share-of-voice analysis across AI platforms.",
        "tags": [
          "AI Visibility"
        ],
        "responses": {
          "200": {
            "description": "Competitor analysis",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "domain": {
                            "type": "string"
                          },
                          "variants": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "latest_visibility_score": {
                            "type": "number",
                            "nullable": true
                          },
                          "last_tracked_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "share_of_voice": {
                            "type": "object",
                            "description": "The competitor's mentions and scores over the window, counted from its daily rows. Changed 2026-10-01: a re-read of stored answers now recounts each day's rows from 2026-05-27 on under the competitor's current name and other names, so the totals for those days can change after a rename; days before 2026-05-27 keep their counts. Changed 2026-10-01: a name that is an ordinary word or a place, or is made only of them (\"Landing\", \"Home Instead\", \"Visit Mobile\"), counts only where the answer writes it as a name, every significant word capitalised, or links the entity's own site; answers read from this date on are counted this way, and a re-read applies it to earlier days.",
                            "properties": {
                              "total_mentions": {
                                "type": "integer"
                              },
                              "avg_score": {
                                "type": "number",
                                "nullable": true,
                                "description": "Mean visibility score over the competitor's measured rows in the window (one decimal). Null when the competitor has no measured row in the window. Changed 2026-09-19: previously a running average seeded at 0, and 0 with nothing measured."
                              },
                              "platforms": {
                                "type": "object"
                              }
                            }
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 30
            },
            "description": "Lookback period in days"
          }
        ]
      }
    },
    "/ai-visibility/alerts": {
      "get": {
        "operationId": "getAIVisibilityAlerts",
        "summary": "Get visibility alerts",
        "description": "Get alerts for visibility changes.",
        "tags": [
          "AI Visibility"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "unread",
                "resolved",
                "all"
              ]
            },
            "description": "Filter by alert status"
          },
          {
            "name": "severity",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "low",
                "medium",
                "high",
                "critical"
              ]
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "visibility_increase",
                "visibility_decrease",
                "new_mention",
                "lost_mention",
                "competitor_overtake",
                "citation_gained",
                "citation_lost",
                "crawler_spike"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of alerts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "type": {
                            "type": "string"
                          },
                          "severity": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "data": {
                            "type": "object"
                          },
                          "platform": {
                            "type": "string",
                            "nullable": true
                          },
                          "is_read": {
                            "type": "boolean"
                          },
                          "read_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "resolved_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "prompt_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "site_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/ai-visibility/insights": {
      "get": {
        "operationId": "getAIVisibilityInsights",
        "summary": "Get optimization insights",
        "description": "Get AI-generated insights for improving visibility.",
        "tags": [
          "AI Visibility"
        ],
        "responses": {
          "200": {
            "description": "Optimization insights",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "type": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "gap_type": {
                            "type": "string",
                            "nullable": true
                          },
                          "diagnosis": {
                            "type": "string",
                            "nullable": true
                          },
                          "confidence_score": {
                            "type": "number",
                            "nullable": true
                          },
                          "target_url": {
                            "type": "string",
                            "nullable": true
                          },
                          "winning_competitor_url": {
                            "type": "string",
                            "nullable": true
                          },
                          "prompt_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updated_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "idle",
                "scraping",
                "analyzing",
                "ready",
                "applied",
                "failed"
              ]
            }
          }
        ]
      }
    },
    "/ai-visibility/crawler-logs": {
      "get": {
        "operationId": "getAICrawlerLogs",
        "summary": "Get AI crawler logs",
        "description": "View AI bot activity on your sites.\n\n### 2026-10-05 - grouped `platforms` is an array\n\nBREAKING for clients that parsed the old string: with `group_by=day` or `group_by=path`, each row's `platforms` is now a JSON array of platform names (`[\"chatgpt\", \"claude\"]`). It used to arrive as the Postgres array literal string `\"{chatgpt,claude}\"`.",
        "tags": [
          "AI Visibility"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "platform",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 30,
              "maximum": 90
            }
          },
          {
            "name": "group_by",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "none",
                "day",
                "platform",
                "path"
              ],
              "default": "none"
            },
            "description": "Group results by dimension"
          }
        ],
        "responses": {
          "200": {
            "description": "Crawler logs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "site_id": {
                            "type": "string"
                          },
                          "site_domain": {
                            "type": "string"
                          },
                          "platform": {
                            "type": "string"
                          },
                          "bot_name": {
                            "type": "string"
                          },
                          "user_agent": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "path": {
                            "type": "string"
                          },
                          "status_code": {
                            "type": "integer"
                          },
                          "was_blocked": {
                            "type": "boolean"
                          },
                          "crawled_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/analytics/gsc/overview": {
      "get": {
        "operationId": "getGSCOverview",
        "summary": "Get GSC overview",
        "description": "Get Google Search Console overview with 28-day comparison.",
        "tags": [
          "Analytics"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "GSC overview data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "site_id": {
                          "type": "string"
                        },
                        "site_domain": {
                          "type": "string"
                        },
                        "period": {
                          "type": "object",
                          "properties": {
                            "current": {
                              "type": "object",
                              "properties": {
                                "start": {
                                  "type": "string"
                                },
                                "end": {
                                  "type": "string"
                                }
                              }
                            },
                            "previous": {
                              "type": "object",
                              "properties": {
                                "start": {
                                  "type": "string"
                                },
                                "end": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        },
                        "metrics": {
                          "type": "object",
                          "properties": {
                            "clicks": {
                              "type": "object",
                              "properties": {
                                "current": {
                                  "type": "integer"
                                },
                                "previous": {
                                  "type": "integer"
                                },
                                "change_percent": {
                                  "type": "number"
                                }
                              }
                            },
                            "impressions": {
                              "type": "object",
                              "properties": {
                                "current": {
                                  "type": "integer"
                                },
                                "previous": {
                                  "type": "integer"
                                },
                                "change_percent": {
                                  "type": "number"
                                }
                              }
                            },
                            "ctr": {
                              "type": "object",
                              "properties": {
                                "current": {
                                  "type": "number"
                                },
                                "previous": {
                                  "type": "number"
                                },
                                "change_percent": {
                                  "type": "number"
                                }
                              }
                            },
                            "position": {
                              "type": "object",
                              "properties": {
                                "current": {
                                  "type": "number"
                                },
                                "previous": {
                                  "type": "number"
                                },
                                "change_percent": {
                                  "type": "number"
                                }
                              }
                            }
                          }
                        },
                        "summary": {
                          "type": "object",
                          "properties": {
                            "unique_queries": {
                              "type": "integer"
                            },
                            "unique_pages": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/analytics/gsc/queries": {
      "get": {
        "operationId": "getGSCQueries",
        "summary": "Get top queries",
        "description": "Get top search queries from GSC.",
        "tags": [
          "Analytics"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 500
            }
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 28
            }
          },
          {
            "name": "sort_by",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "clicks",
                "impressions",
                "ctr",
                "position"
              ],
              "default": "clicks"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Top queries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "query": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          },
                          "impressions": {
                            "type": "integer"
                          },
                          "ctr": {
                            "type": "number"
                          },
                          "position": {
                            "type": "number"
                          },
                          "pages_count": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/analytics/gsc/pages": {
      "get": {
        "operationId": "getGSCPages",
        "summary": "Get top pages",
        "description": "Get top pages by performance from GSC.",
        "tags": [
          "Analytics"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 28
            }
          },
          {
            "name": "sort_by",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "clicks",
                "impressions",
                "ctr",
                "position"
              ],
              "default": "clicks"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Top pages",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "page_url": {
                            "type": "string"
                          },
                          "content_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "content_title": {
                            "type": "string",
                            "nullable": true
                          },
                          "clicks": {
                            "type": "integer"
                          },
                          "impressions": {
                            "type": "integer"
                          },
                          "ctr": {
                            "type": "number"
                          },
                          "position": {
                            "type": "number"
                          },
                          "queries_count": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/analytics/gaps": {
      "get": {
        "operationId": "getContentGaps",
        "summary": "Get content gaps",
        "description": "Get content gap opportunities. By default the response EXCLUDES dismissed, completed and auto_resolved opportunities; pass ?status= to request them explicitly. The default response also EXCLUDES rows judged off-strategy - no cluster fit and no evidence from a CONFIRMED competitor (competitor URLs belonging to competitors still awaiting your review do not count, and relevance.reason then reads 'a competitor ranks for it, but that competitor is awaiting your review'); pass ?include_off_strategy=true to include them. `competitor_urls` is filtered to confirmed competitors' hosts. Requesting a terminal status (completed, dismissed, auto_resolved) always returns the full set for that status - a strategy filter never hides history. An unrecognized status or type value returns 400 rather than being ignored.\n\n### 2026-08-17 - Competitors are confirmed, not assumed\n\nBREAKING for default result sets: rows whose only competitor evidence belongs to unconfirmed competitors now default-exclude as off-strategy, and `competitor_urls` no longer includes unconfirmed competitors' hosts. Confirm competitors in Brand Hub to restore their evidence.",
        "tags": [
          "Analytics"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "new",
                "reviewed",
                "in_progress",
                "dismissed",
                "completed",
                "auto_resolved"
              ]
            },
            "description": "Filter by a single status. Omit for the default view, which excludes dismissed, completed and auto_resolved."
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "missing_content",
                "thin_content",
                "outdated_content",
                "competitor_gap"
              ]
            }
          },
          {
            "name": "include_off_strategy",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Include rows the default response filters out as off-strategy. Empty means not supplied; any other non-boolean value returns 400."
          }
        ],
        "responses": {
          "200": {
            "description": "Content gaps",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "site_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "site_domain": {
                            "type": "string",
                            "nullable": true
                          },
                          "keyword": {
                            "type": "string"
                          },
                          "search_volume": {
                            "type": "integer",
                            "nullable": true
                          },
                          "difficulty": {
                            "type": "number",
                            "nullable": true
                          },
                          "opportunity_type": {
                            "type": "string"
                          },
                          "impressions": {
                            "type": "integer",
                            "nullable": true
                          },
                          "clicks": {
                            "type": "integer",
                            "nullable": true
                          },
                          "avg_position": {
                            "type": "number",
                            "nullable": true
                          },
                          "page_url": {
                            "type": "string",
                            "nullable": true
                          },
                          "existing_content_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "suggested_brief_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "competitor_urls": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "nullable": true
                          },
                          "competitor_analysis": {
                            "type": "object",
                            "nullable": true
                          },
                          "status": {
                            "type": "string"
                          },
                          "relevance": {
                            "type": "object",
                            "nullable": true,
                            "description": "How far this topic travels. Suggestion rows carry the derived bucket and reason; update rows about your OWN pages are always confident. Makes include_off_strategy and the terminal-status exemption actionable.",
                            "properties": {
                              "bucket": {
                                "type": "string",
                                "enum": [
                                  "confident",
                                  "uncertain",
                                  "off_strategy"
                                ]
                              },
                              "reason": {
                                "type": "string"
                              }
                            }
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updated_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid status, type or site_id value"
          }
        }
      }
    },
    "/opportunities": {
      "get": {
        "operationId": "listOpportunities",
        "summary": "List opportunities",
        "description": "Unified opportunity list across gap, programmatic and decay sources. By default the response EXCLUDES dismissed, completed and auto_resolved opportunities; pass ?status= to request a specific status explicitly. The default response also EXCLUDES rows judged off-strategy (no cluster fit and no evidence tying the topic to your site); pass ?include_off_strategy=true to see them - each row's `relevance` field carries the bucket and reason. `auto_resolved` means a scan found the site already covers the topic — it is distinct from `dismissed` (a user signal) and `completed` (published from the row). An unrecognized status returns 400 rather than being ignored.",
        "tags": [
          "Opportunities"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "view",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "quick-wins",
                "growth",
                "strategic"
              ],
              "default": "all"
            }
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "gsc",
                "competitor",
                "programmatic",
                "decay"
              ],
              "default": "all"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "new",
                "reviewed",
                "in_progress",
                "completed",
                "dismissed",
                "auto_resolved"
              ]
            },
            "description": "Filter by a single status. Omit for the default view, which excludes dismissed, completed and auto_resolved."
          },
          {
            "name": "include_off_strategy",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            },
            "description": "Off-strategy rows (no cluster fit and no first-party evidence, or matching a never-write-about term) are excluded from every default list. Pass true to include them; each row's relevance field carries the bucket and reason."
          }
        ],
        "responses": {
          "200": {
            "description": "Opportunities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string",
                            "nullable": true
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "gsc",
                              "competitor",
                              "programmatic",
                              "decay"
                            ]
                          },
                          "action": {
                            "type": "string",
                            "enum": [
                              "update",
                              "create",
                              "batch"
                            ]
                          },
                          "view": {
                            "type": "string",
                            "enum": [
                              "quick-wins",
                              "growth",
                              "strategic"
                            ]
                          },
                          "scores": {
                            "type": "object",
                            "properties": {
                              "overall": {
                                "type": "number"
                              },
                              "effort": {
                                "type": "object"
                              },
                              "impact": {
                                "type": "object"
                              },
                              "speed": {
                                "type": "object"
                              },
                              "strategic": {
                                "type": "object"
                              }
                            }
                          },
                          "confidence": {
                            "type": "string",
                            "enum": [
                              "high",
                              "medium",
                              "low"
                            ]
                          },
                          "relevance": {
                            "type": "object",
                            "nullable": true,
                            "description": "How far this topic travels. off_strategy rows appear only when include_off_strategy=true; uncertain rows are listed but demoted and never auto-publish.",
                            "properties": {
                              "bucket": {
                                "type": "string",
                                "enum": [
                                  "confident",
                                  "uncertain",
                                  "off_strategy"
                                ]
                              },
                              "reason": {
                                "type": "string"
                              }
                            }
                          },
                          "estimated_traffic": {
                            "type": "integer",
                            "nullable": true
                          },
                          "search_volume": {
                            "type": "integer",
                            "nullable": true
                          },
                          "current_position": {
                            "type": "number",
                            "nullable": true
                          },
                          "difficulty": {
                            "type": "integer",
                            "nullable": true
                          },
                          "page_count": {
                            "type": "integer",
                            "nullable": true
                          },
                          "programmatic_type": {
                            "type": "string",
                            "nullable": true
                          },
                          "site_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "site_domain": {
                            "type": "string",
                            "nullable": true
                          },
                          "existing_content_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "existing_content_title": {
                            "type": "string",
                            "nullable": true
                          },
                          "cluster_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "cluster_name": {
                            "type": "string",
                            "nullable": true
                          },
                          "competitors": {
                            "type": "array",
                            "nullable": true,
                            "items": {
                              "type": "object",
                              "properties": {
                                "domain": {
                                  "type": "string"
                                },
                                "position": {
                                  "type": "integer",
                                  "nullable": true
                                },
                                "url": {
                                  "type": "string",
                                  "nullable": true
                                }
                              }
                            }
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "new",
                              "reviewed",
                              "in_progress",
                              "completed",
                              "dismissed",
                              "auto_resolved",
                              "unknown"
                            ],
                            "description": "`unknown` is a read-time value for a DB string outside the known set; no row is created with it."
                          },
                          "detected_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "last_analyzed_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "page_size": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "has_more": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter"
          }
        }
      }
    },
    "/analytics/alerts": {
      "get": {
        "operationId": "getPerformanceAlerts",
        "summary": "Get performance alerts",
        "description": "Get performance alerts (traffic drops, etc.).",
        "tags": [
          "Analytics"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "unresolved",
                "resolved",
                "all"
              ]
            },
            "description": "Filter by resolution status"
          },
          {
            "name": "severity",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "low",
                "medium",
                "high",
                "critical"
              ]
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ranking_drop",
                "traffic_drop",
                "decay_detected"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Performance alerts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "content_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "content_title": {
                            "type": "string",
                            "nullable": true
                          },
                          "content_status": {
                            "type": "string",
                            "nullable": true
                          },
                          "type": {
                            "type": "string"
                          },
                          "severity": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "data": {
                            "type": "object"
                          },
                          "has_optimization": {
                            "type": "boolean"
                          },
                          "resolved_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "resolution": {
                            "type": "string",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/analytics/alerts/{id}/resolve": {
      "post": {
        "operationId": "resolveAlert",
        "summary": "Resolve alert",
        "description": "Mark an alert as resolved.",
        "tags": [
          "Analytics"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "resolution": {
                    "type": "string",
                    "maxLength": 1000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Alert resolved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "resolved_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "resolution": {
                          "type": "string",
                          "nullable": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/serp/analyze": {
      "post": {
        "operationId": "analyzeSERP",
        "summary": "Analyze SERP",
        "description": "Analyze search results for a keyword, including AI Overview and PAA.",
        "tags": [
          "SERP"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "keyword"
                ],
                "properties": {
                  "keyword": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 200
                  },
                  "location": {
                    "type": "string",
                    "default": "United States"
                  },
                  "country_code": {
                    "type": "string",
                    "default": "us"
                  },
                  "language_code": {
                    "type": "string",
                    "default": "en"
                  },
                  "num": {
                    "type": "integer",
                    "default": 10,
                    "maximum": 20,
                    "minimum": 5,
                    "description": "Number of SERP results to fetch"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SERP analysis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SERPAnalysis"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/serp/competitors": {
      "post": {
        "operationId": "analyzeCompetitors",
        "summary": "Analyze competitors",
        "description": "Compare a URL against SERP competitors for a keyword.",
        "tags": [
          "SERP"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "keyword",
                  "url"
                ],
                "properties": {
                  "keyword": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "location": {
                    "type": "string"
                  },
                  "country_code": {
                    "type": "string"
                  },
                  "language_code": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Competitor analysis",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "keyword": {
                          "type": "string"
                        },
                        "target_url": {
                          "type": "string"
                        },
                        "target_domain": {
                          "type": "string"
                        },
                        "search_parameters": {
                          "type": "object"
                        },
                        "target_visibility": {
                          "type": "object",
                          "properties": {
                            "is_ranking": {
                              "type": "boolean"
                            },
                            "position": {
                              "type": "integer",
                              "nullable": true
                            },
                            "title": {
                              "type": "string",
                              "nullable": true
                            },
                            "snippet": {
                              "type": "string",
                              "nullable": true
                            }
                          }
                        },
                        "competitive_analysis": {
                          "type": "object",
                          "properties": {
                            "total_competitors": {
                              "type": "integer"
                            },
                            "competitors": {
                              "type": "array",
                              "items": {
                                "type": "object"
                              }
                            }
                          }
                        },
                        "opportunities": {
                          "type": "object"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/serp/intent": {
      "post": {
        "operationId": "classifyIntent",
        "summary": "Classify search intent",
        "description": "Classify the search intent for a keyword.",
        "tags": [
          "SERP"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "keyword"
                ],
                "properties": {
                  "keyword": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Intent classification",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "keyword": {
                          "type": "string"
                        },
                        "search_parameters": {
                          "type": "object"
                        },
                        "intent_classification": {
                          "type": "object",
                          "properties": {
                            "primary_intent": {
                              "type": "string"
                            },
                            "confidence": {
                              "type": "number"
                            },
                            "scores": {
                              "type": "object",
                              "properties": {
                                "informational": {
                                  "type": "number"
                                },
                                "navigational": {
                                  "type": "number"
                                },
                                "transactional": {
                                  "type": "number"
                                },
                                "commercial": {
                                  "type": "number"
                                }
                              }
                            }
                          }
                        },
                        "serp_signals": {
                          "type": "object"
                        },
                        "recommendations": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "content_type_suggestions": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/auto-optimization/status": {
      "get": {
        "operationId": "getAutoOptimizationStatus",
        "summary": "Get auto-optimization status",
        "description": "Auto-optimization status for a site, and optionally for one content piece. `auto_apply_types` and `auto_apply_confidence_threshold` are the EFFECTIVE policy: the site's own auto-apply settings already narrowed by the workspace policy (Content Guard). When a workspace policy is saved, the allowed types are the intersection of the site's and the workspace's, and the confidence threshold is the stricter of the two. `workspace_policy_applied` tells you whether a saved workspace policy contributed to these values (it may confirm rather than narrow them), so a site-level setting can be told apart from a workspace-governed one. The write side differs: POST /auto-optimization/toggle echoes the raw persisted site settings, not these effective values. An empty `auto_apply_types` means nothing is applied automatically and every suggestion waits for review.",
        "tags": [
          "Optimizations"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Site to report on."
          },
          {
            "name": "content_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional: include optimization details for this content piece."
          }
        ],
        "responses": {
          "200": {
            "description": "Auto-optimization status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "site_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "site_name": {
                          "type": "string"
                        },
                        "site_domain": {
                          "type": "string"
                        },
                        "enabled": {
                          "type": "boolean",
                          "description": "Site-level auto-optimization toggle."
                        },
                        "auto_apply_types": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Effective allowed suggestion types, after the workspace policy is applied."
                        },
                        "auto_apply_confidence_threshold": {
                          "type": "integer",
                          "description": "Effective confidence threshold: the stricter of the site and workspace values."
                        },
                        "workspace_policy_applied": {
                          "type": "boolean",
                          "description": "True when a saved workspace policy contributed to the two fields above (it may confirm rather than narrow them)."
                        },
                        "pending_review_count": {
                          "type": "integer"
                        },
                        "active_optimization_count": {
                          "type": "integer"
                        },
                        "content": {
                          "type": "object",
                          "nullable": true,
                          "description": "Present only when content_id is supplied.",
                          "properties": {
                            "content_id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "content_title": {
                              "type": "string"
                            },
                            "site_id": {
                              "type": "string",
                              "nullable": true
                            },
                            "optimizations": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  "status": {
                                    "type": "string"
                                  },
                                  "suggestions_count": {
                                    "type": "integer"
                                  },
                                  "applied_count": {
                                    "type": "integer"
                                  },
                                  "created_at": {
                                    "type": "string",
                                    "format": "date-time"
                                  },
                                  "analyzed_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/optimizations": {
      "get": {
        "operationId": "listOptimizations",
        "summary": "List optimizations",
        "description": "List content optimization analyses.",
        "tags": [
          "Optimizations"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "analyzing",
                "ready",
                "auto_applying",
                "applied",
                "dismissed",
                "failed"
              ]
            }
          },
          {
            "name": "content_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by content ID"
          }
        ],
        "responses": {
          "200": {
            "description": "List of optimizations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "content_id": {
                            "type": "string"
                          },
                          "alert_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string"
                          },
                          "suggestions_count": {
                            "type": "integer"
                          },
                          "applied_count": {
                            "type": "integer"
                          },
                          "error": {
                            "type": "string",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updated_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "analyzed_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "startOptimization",
        "summary": "Start optimization",
        "description": "Start optimization analysis for content.",
        "tags": [
          "Optimizations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "content_id"
                ],
                "properties": {
                  "content_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "alert_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional performance alert that triggered this optimization"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Optimization started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "content_id": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/optimizations/{id}": {
      "get": {
        "operationId": "getOptimization",
        "summary": "Get optimization",
        "description": "Get optimization details and suggestions.",
        "tags": [
          "Optimizations"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Optimization details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "content_id": {
                          "type": "string"
                        },
                        "content_title": {
                          "type": "string",
                          "nullable": true
                        },
                        "content_status": {
                          "type": "string",
                          "nullable": true
                        },
                        "alert_id": {
                          "type": "string",
                          "nullable": true
                        },
                        "status": {
                          "type": "string"
                        },
                        "competitor_analysis": {
                          "type": "object",
                          "nullable": true
                        },
                        "suggestions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string"
                              },
                              "title": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "priority": {
                                "type": "string"
                              },
                              "content": {
                                "type": "string",
                                "nullable": true
                              },
                              "auto_applyable": {
                                "type": "boolean"
                              },
                              "is_applied": {
                                "type": "boolean"
                              }
                            }
                          }
                        },
                        "applied_suggestion_ids": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "error": {
                          "type": "string",
                          "nullable": true
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "analyzed_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/optimizations/{id}/apply": {
      "post": {
        "operationId": "applyOptimization",
        "summary": "Apply suggestion",
        "description": "Apply an optimization suggestion.",
        "tags": [
          "Optimizations"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "suggestion_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Suggestion applied",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "suggestion_id": {
                          "type": "string"
                        },
                        "suggestion_type": {
                          "type": "string"
                        },
                        "suggestion_title": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/optimizations/{id}/dismiss": {
      "post": {
        "operationId": "dismissOptimization",
        "summary": "Dismiss optimization",
        "description": "Dismiss an optimization.",
        "tags": [
          "Optimizations"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Optimization dismissed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "reason": {
                          "type": "string",
                          "nullable": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "description": "Optional reason for dismissing",
                    "maxLength": 1000
                  }
                }
              }
            }
          }
        }
      }
    },
    "/optimizations/insights": {
      "get": {
        "operationId": "getOptimizationInsights",
        "summary": "Get learning insights",
        "description": "Get insights about what's working based on optimization outcomes.",
        "tags": [
          "Optimizations"
        ],
        "responses": {
          "200": {
            "description": "Learning insights",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "period": {
                          "type": "object",
                          "properties": {
                            "days": {
                              "type": "integer"
                            },
                            "since": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        },
                        "summary": {
                          "type": "object",
                          "properties": {
                            "total_optimizations_measured": {
                              "type": "integer"
                            },
                            "total_improved": {
                              "type": "integer"
                            },
                            "overall_success_rate": {
                              "type": "number"
                            }
                          }
                        },
                        "insights_by_type": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "suggestion_type": {
                                "type": "string"
                              },
                              "total_applied": {
                                "type": "integer"
                              },
                              "successful_count": {
                                "type": "integer"
                              },
                              "success_rate": {
                                "type": "number"
                              },
                              "avg_position_improvement": {
                                "type": "number"
                              },
                              "avg_clicks_change": {
                                "type": "number"
                              }
                            }
                          }
                        },
                        "top_performers": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "recommendations": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 30,
              "minimum": 7,
              "maximum": 90
            },
            "description": "Lookback period in days"
          }
        ]
      }
    },
    "/me": {
      "get": {
        "operationId": "getMe",
        "summary": "Get account identity",
        "description": "The organization this API key belongs to. Built for integration surfaces that label a connection (a Zapier connection label, an MCP client asking \"which Frase account is this?\").\n\nThis endpoint does NOT consume a metered request, and needs no particular scope beyond a valid key. Both are deliberate: connection tests re-run on a schedule, so an account would otherwise pay quota for merely being connected, and a key holding only write scopes still belongs to an account its owner needs to recognize.\n\n`organization_name` can be null for a short window after the key was first cached; retry on the next test.",
        "tags": [
          "Usage"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The calling key's organization.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "organization_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "The organization the API key is scoped to."
                        },
                        "organization_name": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The organization's display name. Null only briefly for keys cached before this field existed."
                        }
                      },
                      "required": [
                        "organization_id",
                        "organization_name"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/usage": {
      "get": {
        "operationId": "getUsage",
        "summary": "Get usage and quota",
        "description": "What each pool has used, its limit, when it refills, and what has recently been refused.\n\nThis endpoint does NOT consume a metered request, and needs no particular scope beyond a valid key. Both are deliberate: the callers who most need to read their quota are the ones who have run out, and a key holding only write scopes still has to be able to discover why its writes started failing.\n\nUse it to pace work before a large batch, and to interpret a 429 after one.\n\n### 2026-10-22 - resources adds ai_visibility_prompts\n\nAdditive: `resources` gains an `ai_visibility_prompts` key with the same shape as `domains` and `seats` (tracked AI Visibility prompts against the organization's active-prompt cap; no `resets_at`). A client that iterates every resource key sees one more entry; no existing key or field changed.",
        "tags": [
          "Usage"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "include_denials",
            "in": "query",
            "description": "Set to false to omit recent_denials.",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current usage, limits and recent denials",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "plan": {
                          "type": "string"
                        },
                        "subscription_status": {
                          "type": "string"
                        },
                        "subscription_blocked": {
                          "type": "boolean",
                          "description": "True when the subscription itself blocks work, regardless of remaining quota: every pool can read healthy and every call still fail. The remedy differs from an exhausted pool - resubscribe, rather than wait for a reset or upgrade."
                        },
                        "meters": {
                          "type": "object",
                          "description": "Consumption pools that refill when the usage window rolls. Keys: articles, audit_pages, ai_prompts, research, api_requests, hero_images, diagrams.",
                          "additionalProperties": {
                            "$ref": "#/components/schemas/UsageMeter"
                          }
                        },
                        "resources": {
                          "type": "object",
                          "description": "Standing allowances that do not refill, so they carry no resets_at. Keys: domains, seats, ai_visibility_prompts (tracked AI Visibility prompts against the organization's active-prompt cap).",
                          "additionalProperties": {
                            "$ref": "#/components/schemas/UsageResource"
                          }
                        },
                        "recent_denials": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/UsageDenial"
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/webhooks": {
      "get": {
        "operationId": "listWebhooks",
        "summary": "List webhooks",
        "description": "List all webhook subscriptions.",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of webhooks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "events": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "is_active": {
                            "type": "boolean"
                          },
                          "stats": {
                            "type": "object",
                            "properties": {
                              "success_count": {
                                "type": "integer"
                              },
                              "failure_count": {
                                "type": "integer"
                              },
                              "last_delivery_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              },
                              "last_success_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              },
                              "last_failure_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              },
                              "last_failure_reason": {
                                "type": "string",
                                "nullable": true
                              }
                            }
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updated_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createWebhook",
        "summary": "Create webhook",
        "description": "Create a new webhook subscription. The secret is only returned once.\n\n## Delivery\n\nEvery delivery is an HTTPS `POST` to your URL (port 443, public address, no redirects) with `Content-Type: application/json` and these headers:\n\n- `X-Webhook-Event`: the event name, e.g. `content.ready`. The same name is also in the body as `event`, so it is covered by the signature; prefer the body value.\n- `X-Webhook-Id`: stable per event. Every retry of one event to one webhook carries the same value, so drop any delivery whose id you have already processed.\n- `X-Webhook-Timestamp`: unix seconds\n- `X-Webhook-Signature`: `v1=<hex HMAC-SHA256 of \"<timestamp>.<raw body>\" using the webhook secret>`\n\nAny non-2xx response is retried up to three more times. Ten consecutive failed events pause the subscription.\n\n### 2026-10-15 — Citation Engine approval lifecycle v2\n\nBREAKING for Citation Engine webhook consumers: Citation Engine payloads now carry `schemaVersion: 2`. Staff approval emits `content.ready` (`stage: ready`, `readyAt`). `content.approved` (`stage: approved`, `approvedAt`) means every assigned client approved this exact revision, or staff explicitly approved it under current account-wide delegation. It no longer means staff review alone. Unmanaged content generation events are unchanged.\n\nBefore rollout, subscribe to `content.ready` for review intake; retain `content.approved` for delivery automation. Do not publish a `content.ready` document automatically. Read `approvals.mode`, revision fingerprint/version, authenticated document links and `nextAction`. Assign client approvers in each account's existing Delivery → Client profile configuration, or explicitly grant staff delegation there. Empty approver lists require configuration and do not imply consent.\n\nAlready delivered revisions retain their receipts. Undelivered historical approvals require explicit client consent or a fresh staff approval after delegation; they are never silently backfilled as delegated. Legacy reviewed fixes can continue into the checked review flow without re-generating their accepted text. Event names retain their subscription and signature envelope; only Citation Engine payload/approval semantics are versioned. See the Citation approval rollout guide in the repository for the operator preflight and recovery procedure.",
        "tags": [
          "Webhooks"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "url",
                  "events"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Must be HTTPS"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "content.ready",
                        "content.approved",
                        "content.published",
                        "brief.ready",
                        "research.completed",
                        "audit.completed",
                        "optimization.ready",
                        "ai_visibility.alert",
                        "performance.alert",
                        "atomization.ready"
                      ]
                    }
                  },
                  "is_active": {
                    "type": "boolean",
                    "default": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook created with secret",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookWithSecret"
                }
              }
            }
          }
        }
      }
    },
    "/webhooks/{id}": {
      "get": {
        "operationId": "getWebhook",
        "summary": "Get webhook",
        "description": "Get webhook details (secret is not included).",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "events": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "is_active": {
                          "type": "boolean"
                        },
                        "config": {
                          "type": "object",
                          "properties": {
                            "max_retries": {
                              "type": "integer"
                            },
                            "retry_delay_seconds": {
                              "type": "integer"
                            }
                          }
                        },
                        "stats": {
                          "type": "object",
                          "properties": {
                            "success_count": {
                              "type": "integer"
                            },
                            "failure_count": {
                              "type": "integer"
                            },
                            "last_delivery_at": {
                              "type": "string",
                              "format": "date-time",
                              "nullable": true
                            },
                            "last_success_at": {
                              "type": "string",
                              "format": "date-time",
                              "nullable": true
                            },
                            "last_failure_at": {
                              "type": "string",
                              "format": "date-time",
                              "nullable": true
                            },
                            "last_failure_reason": {
                              "type": "string",
                              "nullable": true
                            }
                          }
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateWebhook",
        "summary": "Update webhook",
        "description": "Update webhook settings.",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "is_active": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "events": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "is_active": {
                          "type": "boolean"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "message": {
                          "type": "string"
                        },
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteWebhook",
        "summary": "Delete webhook",
        "description": "Delete a webhook subscription.",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{id}/status": {
      "get": {
        "operationId": "getJobStatus",
        "summary": "Get job status",
        "description": "Check the status of an async job (audit, research, content, brief, optimization, atomization).",
        "tags": [
          "Jobs"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "audit",
                "research",
                "content",
                "brief",
                "optimization",
                "atomization"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Job status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobStatus"
                }
              }
            }
          }
        }
      }
    },
    "/competitive-analysis": {
      "get": {
        "operationId": "listCompetitiveAnalyses",
        "summary": "List competitive analyses",
        "description": "List all competitive page analyses for your organization.",
        "tags": [
          "Competitive Analysis"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "crawling_page",
                "fetching_rankings",
                "analyzing_competitors",
                "generating_report",
                "ready",
                "failed"
              ]
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by site ID"
          }
        ],
        "responses": {
          "200": {
            "description": "List of competitive analyses",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "url": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "opportunity_score": {
                            "type": "integer",
                            "nullable": true
                          },
                          "error": {
                            "type": "string",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "completed_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "operationId": "startCompetitiveAnalysis",
        "summary": "Start competitive analysis",
        "description": "Start a new competitive page analysis. Crawls the target page, fetches ranking queries, discovers competitors, and generates a gap analysis.",
        "tags": [
          "Competitive Analysis"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Target page URL to analyze"
                  },
                  "competitor_urls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    },
                    "description": "Optional manual competitor URLs. If omitted, competitors are discovered via SERP analysis."
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional site ID to associate the analysis with"
                  },
                  "location_name": {
                    "type": "string",
                    "description": "Location for SERP queries (e.g., 'United States')"
                  },
                  "industry": {
                    "type": "string",
                    "description": "Industry context for the analysis"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Competitive analysis started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "url": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "description": "Audit page limit exceeded"
          }
        }
      }
    },
    "/competitive-analysis/{id}": {
      "get": {
        "operationId": "getCompetitiveAnalysis",
        "summary": "Get competitive analysis",
        "description": "Get detailed results of a competitive analysis including page crawl data, ranking queries, competitor analysis, and gap analysis.",
        "tags": [
          "Competitive Analysis"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Competitive analysis details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "url": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "crawling_page",
                            "fetching_rankings",
                            "analyzing_competitors",
                            "generating_report",
                            "ready",
                            "failed"
                          ]
                        },
                        "manual_competitor_urls": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "nullable": true
                        },
                        "page_crawl": {
                          "type": "object",
                          "nullable": true
                        },
                        "ranking_queries": {
                          "type": "object",
                          "nullable": true
                        },
                        "serp_competitors": {
                          "type": "object",
                          "nullable": true
                        },
                        "competitor_analysis": {
                          "type": "object",
                          "nullable": true
                        },
                        "gap_analysis": {
                          "type": "object",
                          "nullable": true
                        },
                        "opportunity_score": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 100,
                          "nullable": true
                        },
                        "generated_brief_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true
                        },
                        "error": {
                          "type": "string",
                          "nullable": true
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "completed_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "delete": {
        "operationId": "deleteCompetitiveAnalysis",
        "summary": "Delete competitive analysis",
        "description": "Permanently delete a competitive analysis and its results.",
        "tags": [
          "Competitive Analysis"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Analysis deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "deleted": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/competitive-analysis/{id}/generate-brief": {
      "post": {
        "operationId": "generateBriefFromCompetitiveAnalysis",
        "summary": "Generate brief from analysis",
        "description": "Generate an optimization brief from a completed competitive analysis. The analysis must have status 'ready'. This endpoint is idempotent — if a brief was already generated, it returns the existing brief ID.",
        "tags": [
          "Competitive Analysis"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Brief already exists (idempotent)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Brief generated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "brief_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "analysis_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "topic": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Analysis is not in 'ready' status"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/competitive-analysis/locations": {
      "get": {
        "operationId": "searchLocations",
        "summary": "Search locations",
        "description": "Search for geographic locations to use when starting a competitive analysis. Returns location codes, names, and types.",
        "tags": [
          "Competitive Analysis"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2
            },
            "description": "Search query (minimum 2 characters)"
          }
        ],
        "responses": {
          "200": {
            "description": "Location search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "locations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "location_code": {
                                "type": "integer"
                              },
                              "location_name": {
                                "type": "string"
                              },
                              "location_type": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/legacy/process_serp": {
      "post": {
        "operationId": "legacyProcessSerp",
        "summary": "Process SERP (Legacy)",
        "description": "Legacy endpoint for SERP processing. Search Google and process results.",
        "tags": [
          "Legacy"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string"
                  },
                  "count": {
                    "type": "integer",
                    "default": 10
                  },
                  "location": {
                    "type": "string",
                    "description": "Search location"
                  },
                  "language": {
                    "type": "string",
                    "description": "Language code"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SERP results"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/legacy/process_url": {
      "post": {
        "operationId": "legacyProcessUrl",
        "summary": "Process URL (Legacy)",
        "description": "Legacy endpoint for URL processing. Extract content from a URL.",
        "tags": [
          "Legacy"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "only_main_content": {
                    "type": "boolean",
                    "default": true,
                    "description": "Extract only main content, excluding navigation and sidebars"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extracted content"
          }
        }
      }
    },
    "/legacy/get_document_id": {
      "post": {
        "operationId": "legacyGetDocument",
        "summary": "Get document by ID (Legacy)",
        "description": "Legacy endpoint to get a document by ID.",
        "tags": [
          "Legacy"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "doc_id"
                ],
                "properties": {
                  "doc_id": {
                    "type": "string",
                    "description": "The document ID (content or brief UUID)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Document data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "doc_id": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "content",
                        "brief"
                      ]
                    },
                    "title": {
                      "type": "string"
                    },
                    "text": {
                      "type": "string",
                      "nullable": true,
                      "description": "Content body (content type only)"
                    },
                    "status": {
                      "type": "string"
                    },
                    "word_count": {
                      "type": "integer",
                      "nullable": true
                    },
                    "meta_title": {
                      "type": "string",
                      "nullable": true
                    },
                    "meta_description": {
                      "type": "string",
                      "nullable": true
                    },
                    "target_keywords": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "content_type": {
                      "type": "string",
                      "nullable": true,
                      "description": "Brief content type (brief type only)"
                    },
                    "outline": {
                      "type": "array",
                      "nullable": true,
                      "description": "Brief outline (brief type only)"
                    },
                    "target_word_count": {
                      "type": "integer",
                      "nullable": true,
                      "description": "Brief target word count (brief type only)"
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updated_at": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "published_at": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/legacy/get_documents_email": {
      "post": {
        "operationId": "legacyGetDocumentsByEmail",
        "summary": "Get documents by email (Legacy)",
        "description": "Legacy endpoint to get all documents by user email.",
        "tags": [
          "Legacy"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "User email to look up documents for"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "List of documents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "email": {
                      "type": "string"
                    },
                    "user": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "first_name": {
                          "type": "string",
                          "nullable": true
                        },
                        "last_name": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    },
                    "documents": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "doc_id": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "content",
                              "brief"
                            ]
                          },
                          "title": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "word_count": {
                            "type": "integer",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updated_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/rules": {
      "get": {
        "operationId": "listRules",
        "summary": "List rules",
        "description": "Retrieve all content rules for your organization, including system rules and custom rules.",
        "tags": [
          "Rules"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of rules",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedRules"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/rules/{id}": {
      "get": {
        "operationId": "getRule",
        "summary": "Get rule",
        "description": "Retrieve a single content rule by ID.",
        "tags": [
          "Rules"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Rule ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Rule details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RuleDetail"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "deleteRule",
        "summary": "Delete rule",
        "description": "Delete a rule. System rules cannot be deleted.",
        "tags": [
          "Rules"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Rule ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Rule deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "System rule cannot be deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/rule-sets": {
      "get": {
        "operationId": "listRuleSets",
        "summary": "List rule sets",
        "description": "Retrieve all rule sets for your organization, optionally filtered by site.",
        "tags": [
          "Rule Sets"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "description": "Filter rule sets by site",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of rule sets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedRuleSets"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/rule-sets/{id}": {
      "get": {
        "operationId": "getRuleSet",
        "summary": "Get rule set",
        "description": "Retrieve a single rule set by ID, including full rule details.",
        "tags": [
          "Rule Sets"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Rule set ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Rule set details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RuleSetDetail"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "operationId": "deleteRuleSet",
        "summary": "Delete rule set",
        "description": "Delete a rule set. System rule sets cannot be deleted.",
        "tags": [
          "Rule Sets"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Rule set ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Rule set deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "System rule set cannot be deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/playbooks": {
      "get": {
        "operationId": "listPlaybooks",
        "summary": "List playbooks",
        "description": "Retrieve playbooks for your organization.",
        "tags": [
          "Playbooks"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            },
            "description": "Page number"
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Items per page"
          },
          {
            "name": "site_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by site ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of playbooks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PlaybookSummary"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/playbooks/{id}": {
      "get": {
        "operationId": "getPlaybook",
        "summary": "Get playbook",
        "description": "Retrieve a single playbook by ID.",
        "tags": [
          "Playbooks"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Playbook ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Playbook details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Playbook"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "deletePlaybook",
        "summary": "Delete playbook",
        "description": "Delete a playbook. System playbooks cannot be deleted.",
        "tags": [
          "Playbooks"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Playbook ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Playbook deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "System playbook cannot be deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/templates": {
      "get": {
        "operationId": "listTemplates",
        "summary": "List templates",
        "description": "Retrieve all content templates in your organization. Supports pagination and filtering by content type.",
        "tags": [
          "Templates"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "content_type",
            "in": "query",
            "description": "Filter templates by content type",
            "schema": {
              "type": "string",
              "enum": [
                "blog",
                "guide",
                "landing",
                "product",
                "comparison"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of templates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedTemplates"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/templates/{id}": {
      "get": {
        "operationId": "getTemplate",
        "summary": "Get template",
        "description": "Retrieve a specific content template by ID.",
        "tags": [
          "Templates"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Template ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Template details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Template"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "deleteTemplate",
        "summary": "Delete template",
        "description": "Delete a template. System templates cannot be deleted.",
        "tags": [
          "Templates"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Template ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Template deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "System template cannot be deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/cms/posts": {
      "get": {
        "operationId": "listCmsPosts",
        "summary": "List CMS posts",
        "description": "Retrieve CMS posts for a site with optional filtering by status and type.",
        "tags": [
          "CMS"
        ],
        "parameters": [
          {
            "name": "site_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Site ID"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "published",
                "scheduled"
              ]
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "blog_post",
                "page"
              ]
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "created_at",
                "published_at",
                "demand"
              ],
              "default": "created_at"
            },
            "description": "Ordering. `demand` orders posts by the site's own visitor-question demand (highest first), with published_at as tiebreak; posts with no demand signal sort last. Default `created_at` (descending)."
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of CMS posts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CmsPost"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "page_size": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "operationId": "createCmsPost",
        "summary": "Create a CMS post",
        "description": "Create a new post in Frase CMS. CMS must be enabled on the site.",
        "tags": [
          "CMS"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CmsPostInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Post created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CmsPost"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "409": {
            "description": "Review required. The content type is review-gated and the post is not approved yet.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "review_required"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cms/posts/{id}": {
      "get": {
        "operationId": "getCmsPost",
        "summary": "Get a CMS post",
        "description": "Retrieve a single CMS post by ID.",
        "tags": [
          "CMS"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Post ID"
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated list of extra resources to embed. Pass `research` to attach the read-only research-provenance session (`research_session`) that this post's content was generated from. Additive and best-effort: omitting it returns the base post unchanged, and if provenance cannot be resolved (standalone post, or the source research belongs to another organization) the base post is still returned with `research_session: null`."
          }
        ],
        "responses": {
          "200": {
            "description": "Post details. When `include=research` is supplied, `data.research_session` is present (the provenance embed, or `null` when unresolvable).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/CmsPost"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "research_session": {
                              "description": "Research-provenance embed, present only when `include=research` was requested. `null` when the post has no source research or the research belongs to a different organization.",
                              "oneOf": [
                                {
                                  "$ref": "#/components/schemas/CmsResearchSessionEmbed"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "operationId": "updateCmsPost",
        "summary": "Update a CMS post",
        "description": "Update an existing CMS post. Only provided fields are updated.",
        "tags": [
          "CMS"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Post ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CmsPostUpdateInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Post updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CmsPost"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Review required. The content type is review-gated and the post is not approved yet.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "review_required"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteCmsPost",
        "summary": "Delete a CMS post",
        "description": "Delete a CMS post by ID.",
        "tags": [
          "CMS"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Post ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Post deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/cms/posts/{id}/publish": {
      "post": {
        "operationId": "publishCmsPost",
        "summary": "Publish a CMS post",
        "description": "Transition a draft post to published status.",
        "tags": [
          "CMS"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Post ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Post published",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CmsPost"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Review required. The content type is review-gated and the post is not approved yet.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "review_required"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cms/posts/{id}/unpublish": {
      "post": {
        "operationId": "unpublishCmsPost",
        "summary": "Unpublish a CMS post",
        "description": "Transition a published post back to draft status.",
        "tags": [
          "CMS"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Post ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Post unpublished",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CmsPost"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/cms/posts/bulk": {
      "post": {
        "operationId": "bulkCmsPostLifecycle",
        "summary": "Publish, unpublish, or delete many CMS posts at once",
        "description": "Applies one lifecycle action to up to 25 posts in a single request. Each post is processed independently: one failure never aborts the batch, and every id comes back in either `succeeded` or `failed` with a machine-readable `code`. Duplicate ids are deduplicated (first occurrence wins) before processing, so `counts.requested` reflects the deduplicated set. A 200 means the batch was processed, not that every id succeeded - always inspect `failed`. The `delete` action additionally requires the `delete:content` scope.",
        "tags": [
          "CMS"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "action",
                  "post_ids"
                ],
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "publish",
                      "unpublish",
                      "delete"
                    ]
                  },
                  "post_ids": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 25,
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch processed. Inspect `failed` for per-post errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "action": {
                          "type": "string",
                          "enum": [
                            "publish",
                            "unpublish",
                            "delete"
                          ]
                        },
                        "succeeded": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "failed": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "code": {
                                "type": "string",
                                "description": "Machine-readable failure reason, e.g. not_found, rules_blocked, site_feature_disabled, unknown."
                              },
                              "error": {
                                "type": "string",
                                "description": "Human-readable, sanitized message."
                              },
                              "retry_with_force": {
                                "type": "boolean",
                                "description": "True when the failure is a rules_blocked refusal carrying warning-severity content-rule violations only; retrying the identical call with force: true will publish."
                              }
                            }
                          }
                        },
                        "counts": {
                          "type": "object",
                          "properties": {
                            "requested": {
                              "type": "integer",
                              "description": "Size of the deduplicated id set."
                            },
                            "succeeded": {
                              "type": "integer"
                            },
                            "failed": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/cms/posts/import": {
      "post": {
        "operationId": "importCmsPosts",
        "summary": "Bulk import CMS posts",
        "description": "Start an asynchronous bulk import of up to 100 posts. Returns a job ID that can be polled for progress. CMS must be enabled on the target site.",
        "tags": [
          "CMS"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "site_id",
                  "posts"
                ],
                "properties": {
                  "site_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "posts": {
                    "type": "array",
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "required": [
                        "title",
                        "content"
                      ],
                      "properties": {
                        "title": {
                          "type": "string",
                          "maxLength": 500
                        },
                        "content_format": {
                          "type": "string",
                          "enum": [
                            "html",
                            "portable_text"
                          ],
                          "default": "html",
                          "description": "How `content` is encoded. Default `html`. When `portable_text`, `content` is a standard Portable Text blocks array; the server converts it to HTML before the 500KB cap and the sanitize/rehost pipeline. Unknown block types are skipped and logged."
                        },
                        "content": {
                          "description": "Post body. An HTML string when content_format is `html` (default), or a Portable Text blocks array when `portable_text`. The 500KB cap applies to the resulting HTML.",
                          "oneOf": [
                            {
                              "type": "string",
                              "maxLength": 512000
                            },
                            {
                              "type": "array",
                              "items": {
                                "type": "object"
                              }
                            }
                          ]
                        },
                        "slug": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "published",
                            "scheduled"
                          ]
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "blog_post",
                            "page"
                          ]
                        },
                        "excerpt": {
                          "type": "string"
                        },
                        "featured_image": {
                          "type": "string",
                          "format": "uri"
                        },
                        "seo_title": {
                          "type": "string"
                        },
                        "seo_description": {
                          "type": "string"
                        },
                        "focus_keyword": {
                          "type": "string"
                        },
                        "canonical_url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "source_url": {
                          "type": "string",
                          "maxLength": 2048,
                          "description": "The post's URL on its origin site (the old URL before migration). Unlike `canonical_url`, this may be an http(s) absolute URL or a site-relative path. The import registers a 301 redirect from this URL's normalized path to the new post, so existing bookmarks and backlinks keep working; the value is also stored on the post for later internal-link rewriting. Skipped for `page`-type posts (root-routed)."
                        },
                        "published_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Preserved as the post's dateModified instead of being stamped to the import time. Must not be earlier than `published_at`."
                        },
                        "schema_markup": {
                          "type": "object",
                          "description": "JSON-LD structured data for the post. Must include `@context` and `@type`. Additional properties depend on the chosen schema type. See [schema.org](https://schema.org) for full type definitions.",
                          "properties": {
                            "@context": {
                              "type": "string",
                              "default": "https://schema.org",
                              "description": "Schema.org context URL. Almost always `https://schema.org`."
                            },
                            "@type": {
                              "type": "string",
                              "description": "The schema.org type for this content.",
                              "enum": [
                                "Article",
                                "BlogPosting",
                                "NewsArticle",
                                "FAQPage",
                                "HowTo",
                                "TechArticle",
                                "WebPage"
                              ]
                            },
                            "headline": {
                              "type": "string",
                              "description": "The headline of the article. Recommended for Article, BlogPosting, NewsArticle.",
                              "maxLength": 110
                            },
                            "description": {
                              "type": "string",
                              "description": "A short description or summary of the content."
                            },
                            "author": {
                              "oneOf": [
                                {
                                  "type": "object",
                                  "description": "Author as a Person or Organization.",
                                  "properties": {
                                    "@type": {
                                      "type": "string",
                                      "enum": [
                                        "Person",
                                        "Organization"
                                      ]
                                    },
                                    "name": {
                                      "type": "string"
                                    },
                                    "url": {
                                      "type": "string",
                                      "format": "uri"
                                    }
                                  }
                                },
                                {
                                  "type": "array",
                                  "description": "Multiple authors.",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "@type": {
                                        "type": "string",
                                        "enum": [
                                          "Person",
                                          "Organization"
                                        ]
                                      },
                                      "name": {
                                        "type": "string"
                                      },
                                      "url": {
                                        "type": "string",
                                        "format": "uri"
                                      }
                                    }
                                  }
                                }
                              ]
                            },
                            "datePublished": {
                              "type": "string",
                              "format": "date",
                              "description": "Original publication date in ISO 8601 format (e.g., `2026-04-16`)."
                            },
                            "dateModified": {
                              "type": "string",
                              "format": "date",
                              "description": "Last modification date in ISO 8601 format."
                            },
                            "image": {
                              "oneOf": [
                                {
                                  "type": "string",
                                  "format": "uri"
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "@type": {
                                      "type": "string",
                                      "enum": [
                                        "ImageObject"
                                      ]
                                    },
                                    "url": {
                                      "type": "string",
                                      "format": "uri"
                                    },
                                    "width": {
                                      "type": "integer"
                                    },
                                    "height": {
                                      "type": "integer"
                                    }
                                  }
                                }
                              ],
                              "description": "Primary image. Can be a URL string or an ImageObject."
                            },
                            "publisher": {
                              "type": "object",
                              "description": "The publisher of the content.",
                              "properties": {
                                "@type": {
                                  "type": "string",
                                  "enum": [
                                    "Organization"
                                  ]
                                },
                                "name": {
                                  "type": "string"
                                },
                                "logo": {
                                  "type": "object",
                                  "properties": {
                                    "@type": {
                                      "type": "string",
                                      "enum": [
                                        "ImageObject"
                                      ]
                                    },
                                    "url": {
                                      "type": "string",
                                      "format": "uri"
                                    }
                                  }
                                }
                              }
                            },
                            "mainEntity": {
                              "description": "Primary entity of the page. Used by FAQPage (array of Question) and HowTo (HowToStep array).",
                              "oneOf": [
                                {
                                  "type": "array",
                                  "description": "For FAQPage: array of Question objects.",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "@type": {
                                        "type": "string",
                                        "enum": [
                                          "Question"
                                        ]
                                      },
                                      "name": {
                                        "type": "string",
                                        "description": "The question text."
                                      },
                                      "acceptedAnswer": {
                                        "type": "object",
                                        "properties": {
                                          "@type": {
                                            "type": "string",
                                            "enum": [
                                              "Answer"
                                            ]
                                          },
                                          "text": {
                                            "type": "string",
                                            "description": "The answer text."
                                          }
                                        }
                                      }
                                    }
                                  }
                                },
                                {
                                  "type": "object"
                                }
                              ]
                            },
                            "step": {
                              "type": "array",
                              "description": "For HowTo: ordered list of steps.",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "@type": {
                                    "type": "string",
                                    "enum": [
                                      "HowToStep"
                                    ]
                                  },
                                  "name": {
                                    "type": "string",
                                    "description": "Step title."
                                  },
                                  "text": {
                                    "type": "string",
                                    "description": "Step instructions."
                                  },
                                  "image": {
                                    "type": "string",
                                    "format": "uri"
                                  }
                                }
                              }
                            }
                          },
                          "additionalProperties": true
                        },
                        "meta": {
                          "type": "object"
                        },
                        "related_slugs": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "maxItems": 3,
                          "description": "Ordered curated related-post slugs (max 3), resolved to ids in a final pass once every post in the import exists. SETS the relation for published targets on the same site; an empty array is a no-op (use PUT /cms/posts/{id} with related_post_ids: [] to clear). Unresolvable, draft, or cross-site slugs are skipped with warnings."
                        }
                      }
                    }
                  },
                  "options": {
                    "type": "object",
                    "properties": {
                      "on_conflict": {
                        "type": "string",
                        "enum": [
                          "skip",
                          "overwrite"
                        ],
                        "default": "skip",
                        "description": "Behavior when a post with the same slug already exists"
                      },
                      "default_status": {
                        "type": "string",
                        "enum": [
                          "draft",
                          "published",
                          "scheduled"
                        ],
                        "default": "draft",
                        "description": "Default status for posts that don't specify one"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Import job queued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "job_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "queued"
                          ]
                        },
                        "posts_queued": {
                          "type": "integer"
                        },
                        "site_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/cms/posts/import/{jobId}": {
      "get": {
        "operationId": "getCmsImportJobStatus",
        "summary": "Get import job status",
        "description": "Check the progress of a bulk import job. Poll this endpoint until status is `completed` or `failed`.",
        "tags": [
          "CMS"
        ],
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Import job ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Import job status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CmsImportJob"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/content/{id}/comments": {
      "get": {
        "operationId": "listContentComments",
        "summary": "List comments on a content article",
        "description": "Returns a flat list of human + AI comments attached to an article. Clients can rebuild threads via `parent_comment_id` and `root_comment_id`. AI-authored comments visible to the caller are filtered by the same visibility rules used in the app: owners and admins see everything; other members only see AI comments they requested or were @-mentioned in (directly or anywhere in the same thread). API keys without a bound user are treated as admin-equivalent.",
        "tags": [
          "Comments"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Content article UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by comment status. Defaults to `open`.",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "resolved",
                "all"
              ],
              "default": "open"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Flat array of comments for the article.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "comments": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Comment"
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/content/{id}/ai-comments": {
      "post": {
        "operationId": "requestAiComments",
        "summary": "Request AI suggestion comments on a content article",
        "description": "Generates a batch of AI-authored suggestion comments for the article and persists them. Synchronous — returns the created comment IDs and suggestion metadata. Each created comment can subsequently be applied via `POST /content/{id}/ai-comments/{commentId}/apply` or resolved via `PATCH /comments/{commentId}`.",
        "tags": [
          "Comments"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Content article UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sidebar_context": {
                    "type": "string",
                    "description": "Optional extra context (max ~3000 chars) appended to the reviewer prompt."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "AI suggestion comments created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "comments": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/RequestedAiComment"
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/content/{id}/ai-comments/{commentId}/apply": {
      "post": {
        "operationId": "applyAiComment",
        "summary": "Apply an AI suggestion to the content body",
        "description": "Splices the AI comment's `suggested_text` into `content.body` at the comment's anchored selection, then marks the comment as resolved in a single transaction. Refuses to guess when the target text is missing or appears multiple times.",
        "tags": [
          "Comments"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Content article UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "commentId",
            "in": "path",
            "required": true,
            "description": "AI comment UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Suggestion applied. Content body updated and comment resolved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "applied": {
                          "type": "boolean",
                          "enum": [
                            true
                          ]
                        },
                        "content_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "comment_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "word_count": {
                          "type": "integer",
                          "nullable": true
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Comment is not an AI suggestion (missing `suggested_text`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Target text is missing or ambiguous in the draft. Error `code` is one of `target_text_not_found`, `target_text_ambiguous`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/comments/{id}": {
      "patch": {
        "operationId": "setCommentStatus",
        "summary": "Resolve or reopen a comment",
        "description": "Updates the status of a single comment. AI comments not visible to the caller under the visibility gate return 404.",
        "tags": [
          "Comments"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Comment UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "status"
                ],
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "resolved",
                      "open"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Comment status updated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "comment": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "status": {
                              "type": "string",
                              "enum": [
                                "open",
                                "resolved"
                              ]
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/comments/bulk-resolve": {
      "post": {
        "operationId": "bulkSetCommentStatus",
        "summary": "Resolve or reopen many comments at once",
        "description": "Applies the same status to up to 100 comments in a single request. Comments that are missing, deleted, or hidden by the visibility gate are returned in `skipped`.",
        "tags": [
          "Comments"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "comment_ids",
                  "status"
                ],
                "properties": {
                  "comment_ids": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "resolved",
                      "open"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bulk update applied.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "updated": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "skipped": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "reason": {
                                "type": "string",
                                "enum": [
                                  "not_found"
                                ]
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/content/import": {
      "post": {
        "operationId": "importContent",
        "summary": "Import an existing article",
        "description": "Create a Frase document from an article written elsewhere, then score it and build its optimization brief. Supply the body directly (body + body_format) or a source_url for Frase to fetch — the two are mutually exclusive. Takes one article credit per (article, billing period), so regenerating the same article later in the same period does not charge again.\n\n**Retries are safe.** Send an Idempotency-Key header and a repeated request returns 200 with the original content_id instead of importing again. Without the header the key is derived from the request body, so an identical retry is still deduplicated. This matters because a request can be retried automatically on a 5xx, and each import would otherwise take its own credit.",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 255
            },
            "description": "Opaque value making this import replay-safe. Reuse it to retry; change it to import the same article again deliberately."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "The article's title."
                  },
                  "body": {
                    "type": "string",
                    "description": "The article itself. Mutually exclusive with source_url."
                  },
                  "body_format": {
                    "type": "string",
                    "enum": [
                      "markdown",
                      "html"
                    ],
                    "default": "markdown",
                    "description": "How to read body. Declared rather than sniffed: markdown containing an inline <p> would otherwise be mis-parsed, and the scorer branches on the same signal."
                  },
                  "source_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "A page for Frase to fetch instead of sending a body. Mutually exclusive with body."
                  },
                  "target_keywords": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 25,
                    "description": "Keywords the article targets; the first is the primary. Without these the SEO score is computed against an empty set and roughly a third of it is unreachable, so supply them if you have them."
                  },
                  "site_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Site to attach the article to. Omitted, it draws on the org-wide article budget rather than a per-site one."
                  },
                  "content_type": {
                    "type": "string",
                    "description": "e.g. blog_post. Auto-detected when omitted."
                  },
                  "target_word_count": {
                    "type": "integer"
                  },
                  "competitor_urls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    },
                    "maxItems": 10,
                    "description": "Competing pages to research against. Each is validated; a refusal names the offending index."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Imported.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "content_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "brief_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true
                        },
                        "editor_url": {
                          "type": "string",
                          "description": "Deep link to the article in the Frase editor."
                        },
                        "creation_source": {
                          "type": "string",
                          "enum": [
                            "import"
                          ],
                          "description": "Always \"import\": the article was brought in by the customer, not authored by Frase. This is what governs whether the piece may ever auto-publish, so it records AUTHORSHIP, not the door the request came through. The entry surface (e.g. v1_api) is recorded separately on the import summary."
                        },
                        "target_keywords": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The STORED list, echoed back. Deduplicated case-insensitively and capped at 25, so compare against what you sent to see any truncation. Index 0 is primary."
                        },
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Non-fatal advisories. Present and non-empty when the article was imported without target_keywords: keyword coverage and placement are 35 of the SEO score's 100 points, so the score is capped until keywords are set and the article is rescored."
                        },
                        "overage_incurred": {
                          "type": "boolean",
                          "description": "The credit billed as overage rather than coming from the included allowance."
                        },
                        "replayed": {
                          "type": "boolean",
                          "enum": [
                            false
                          ],
                          "description": "Always false on a 201. See the 200 response for the replay case."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "200": {
            "description": "Already imported. Returned when an identical request is retried — matched on the Idempotency-Key header, or on a hash of the request body when that header is absent. The same content_id comes back, no second article credit is taken, and no fetch, scoring or research work is repeated. Note there is no overage_incurred field: nothing was billed on this call.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "content_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "brief_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true
                        },
                        "editor_url": {
                          "type": "string",
                          "description": "Deep link to the article in the Frase editor."
                        },
                        "creation_source": {
                          "type": "string",
                          "enum": [
                            "import"
                          ],
                          "description": "Always \"import\": the article was brought in by the customer, not authored by Frase. This is what governs whether the piece may ever auto-publish, so it records AUTHORSHIP, not the door the request came through. The entry surface (e.g. v1_api) is recorded separately on the import summary."
                        },
                        "target_keywords": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The STORED list, echoed back. Deduplicated case-insensitively and capped at 25, so compare against what you sent to see any truncation. Index 0 is primary."
                        },
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Non-fatal advisories. Present and non-empty when the article was imported without target_keywords: keyword coverage and placement are 35 of the SEO score's 100 points, so the score is capped until keywords are set and the article is rescored."
                        },
                        "replayed": {
                          "type": "boolean",
                          "enum": [
                            true
                          ],
                          "description": "Always true on a 200: this request matched an earlier import and nothing was created."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "description": "The body is larger than the import limit."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "409": {
            "description": "Idempotency-Key conflict, in one of two shapes. `idempotency_key_reuse` — the key was already used for a DIFFERENT request body; returned instead of replaying the earlier article, which would report someone else's import as this caller's success. Use a new key. `import_in_progress` — an import with this key is still running; the response carries Retry-After, and a retry after that delay returns the finished article with a 200. Concurrent retries are serialised by a durable claim, so only one of them performs the fetch, scoring and brief creation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY",
        "description": "API key for authentication. Get your key from Settings > API Keys. You may also send the same key as `Authorization: Bearer <key>` \u2014 see BearerAuth."
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Frase API key (sk_live_* / sk_test_*) or MCP access token (mcp_at_*)",
        "description": "Send either your API key or an MCP access token as `Authorization: Bearer <token>`. An API key sent this way is exactly equivalent to sending it in X-API-KEY \u2014 same identity, same scopes, same rate limits \u2014 so use whichever your HTTP client makes natural. X-API-KEY takes precedence if you somehow send both. Cookie/session auth is intentionally NOT supported on /api/v1/* endpoints."
      }
    },
    "schemas": {
      "FactSource": {
        "type": "object",
        "description": "Where a claim came from, and what we know about the page behind it. `url` and `domain` are absent when the research named a publisher without capturing a link — the common case. A named source is attribution, not grounding: it does not raise `provenance` or `verification`.\n\nADDED 2026-09-14: `state`, `stateReason` and `finding`. Additive and optional — absent on every source minted before that date, and no existing field changed.",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Absent when the source was named but not linked."
          },
          "decision_url": {
            "type": "string",
            "format": "uri",
            "description": "The durable source-decision key. Usually identical to `url`; after a replacement it remains the original URL. Send this value as `source_url` when changing the decision again."
          },
          "title": {
            "type": "string",
            "description": "Publisher or page title."
          },
          "domain": {
            "type": "string",
            "description": "Derived from `url`; absent whenever it is."
          },
          "tier": {
            "type": "string",
            "description": "Authority tier from the citations classifier, when known."
          },
          "verbatimQuote": {
            "type": "string",
            "description": "The excerpt from the source carrying the claim."
          },
          "retrievedAt": {
            "type": "string",
            "format": "date-time"
          },
          "state": {
            "type": "string",
            "enum": [
              "ai_verified",
              "human_verified",
              "unverified",
              "needs_human_check",
              "discarded"
            ],
            "description": "What we know about the page behind `url`. `ai_verified` — we opened it and found the claim, and `verbatimQuote` is copied from it. `human_verified` — a person vouched for it, and re-running research will not change it. `unverified` — nothing established the claim either way; see `stateReason`. `needs_human_check` — the site refused our request, usually bot protection rather than a missing page. `discarded` — the page is gone, so the claim is kept and the link is not usable. Absent on sources minted before 2026-09-14."
          },
          "stateReason": {
            "type": "string",
            "description": "Why `state` is what it is. The one value worth branching on is `unsupported`: the page was READ and the claim was NOT on it, which is a different situation from not having been checked — and the two are indistinguishable from `state` alone, because both are `unverified`. Other values describe the fetch (`http_gone`, `blocked`, `not_parsed`, `unreachable`, `reachable`) and are informational."
          },
          "finding": {
            "type": "string",
            "description": "The checker's own sentence when it read the page and did not find the claim. Model-authored prose meant for a person to read, present only with `stateReason: \"unsupported\"`. Never parse it — branch on `stateReason` and show this."
          }
        }
      },
      "Fact": {
        "type": "object",
        "description": "One claim in a brief's fact ledger. Colour in the UI is provenance x verification; the API returns both so a client can reproduce it.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "claim": {
            "type": "string"
          },
          "figure": {
            "type": "object",
            "nullable": true,
            "description": "The typed number the claim states, when it states one.",
            "properties": {
              "value": {
                "type": "number"
              },
              "unit": {
                "type": "string"
              },
              "asOf": {
                "type": "string"
              }
            }
          },
          "provenance": {
            "type": "string",
            "enum": [
              "research_grounded",
              "research_asserted",
              "customer",
              "imported",
              "generated"
            ]
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FactSource"
            }
          },
          "removed_sources": {
            "type": "array",
            "description": "Decision receipts for sources removed from this claim. They are not citable sources; use their URL to address a later restoring decision.",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "decided_at": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "verification": {
            "type": "string",
            "enum": [
              "verified",
              "undetermined",
              "unverified",
              "refuted",
              "customer_attested"
            ]
          },
          "approval": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected"
            ],
            "description": "Minted facts default to `approved` — the flag is what lets a claim into generation, and a ledger that starts everything at `pending` is a queue nobody works. A rejection is permanent: re-minting the same claim never resets it. Claims the writer asserted in its own output (`provenance: generated`) are the one class held at `pending`."
          },
          "section_binding": {
            "type": "string",
            "nullable": true,
            "description": "Normalised heading this claim belongs to, when bound."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Echo this as `expected_updated_at` on the approval PATCH."
          }
        }
      },
      "BriefSection": {
        "type": "object",
        "properties": {
          "heading": {
            "type": "string"
          },
          "level": {
            "type": "integer",
            "enum": [
              1,
              2,
              3
            ]
          },
          "key_points": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "suggested_word_count": {
            "type": "integer"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "format_instructions": {
            "type": "string",
            "nullable": true
          },
          "owned_keywords": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            }
          },
          "assigned_to": {
            "type": "string",
            "enum": [
              "ai",
              "user"
            ]
          },
          "parent_title": {
            "type": "string",
            "nullable": true
          },
          "evidence": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "UsageMeter": {
        "type": "object",
        "properties": {
          "used": {
            "type": "integer"
          },
          "limit": {
            "type": [
              "integer",
              "null"
            ],
            "description": "null when the plan grants unlimited use of this pool."
          },
          "remaining": {
            "type": [
              "integer",
              "null"
            ],
            "description": "null when unlimited. Never negative - an over-consumed pool reports 0 rather than a negative number a client might read as headroom."
          },
          "unlimited": {
            "type": "boolean"
          },
          "resets_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When this pool refills, or null when there is nothing honest to announce. Null covers three real cases: the reset threshold has passed and the clearing job has not caught up, the subscription status makes the org ineligible for a reset run, and a never-converted trial whose one-time pool never rolls. Treat null as 'unknown', not 'never'."
          },
          "bonus_credits": {
            "type": "integer",
            "description": "Bonus credits already folded into limit. Present only on pools that have them (today: articles, and only when the org holds a balance), absent everywhere else. This is what reconciles remaining with limit - used, which for articles are deliberately different numbers: bonus credits are spent BEFORE the monthly allowance and do not expire with the cycle, so an org past its monthly limit that holds bonus credits genuinely has that many articles left. Recompute the same answer as max(0, (limit - bonus_credits) - used) + bonus_credits."
          }
        }
      },
      "UsageResource": {
        "type": "object",
        "properties": {
          "used": {
            "type": "integer"
          },
          "limit": {
            "type": [
              "integer",
              "null"
            ]
          },
          "remaining": {
            "type": [
              "integer",
              "null"
            ]
          },
          "unlimited": {
            "type": "boolean"
          }
        }
      },
      "UsageDenial": {
        "type": "object",
        "properties": {
          "limit_type": {
            "type": "string",
            "enum": [
              "burst",
              "hourly",
              "monthly",
              "entitlement",
              "subscription",
              "serp_daily"
            ]
          },
          "operation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Which pool refused, for entitlement and subscription denials."
          },
          "endpoint": {
            "type": [
              "string",
              "null"
            ]
          },
          "occurrences": {
            "type": "integer",
            "description": "Denials represented, not rows: repeats for the same limit and endpoint inside a short window are collapsed and counted here."
          },
          "last_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CmsDeliveryPost": {
        "type": "object",
        "description": "A published CMS post served by the public headless-delivery single-post API. snake_case (consistent with the API-key v1 CmsPost). Includes taxonomy (primary_author/authors/category/tags) and all SEO scalars.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "blog_post",
              "page"
            ]
          },
          "title": {
            "type": "string"
          },
          "excerpt": {
            "type": "string",
            "nullable": true
          },
          "featured_image": {
            "type": "string",
            "nullable": true,
            "format": "uri"
          },
          "featured_image_alt": {
            "type": "string",
            "nullable": true
          },
          "seo_title": {
            "type": "string",
            "nullable": true
          },
          "seo_description": {
            "type": "string",
            "nullable": true
          },
          "focus_keyword": {
            "type": "string",
            "nullable": true
          },
          "canonical_url": {
            "type": "string",
            "nullable": true,
            "format": "uri"
          },
          "schema_markup": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "Editor-authored JSON-LD structured data, if set."
          },
          "og_image": {
            "type": "string",
            "nullable": true,
            "format": "uri"
          },
          "og_title": {
            "type": "string",
            "nullable": true
          },
          "og_description": {
            "type": "string",
            "nullable": true
          },
          "published_at": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "primary_author": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "avatar_url": {
                "type": "string",
                "nullable": true,
                "format": "uri"
              },
              "bio": {
                "type": "string",
                "nullable": true
              },
              "role": {
                "type": "string",
                "nullable": true,
                "description": "e.g. \"Head of Content\". Set on author creation only; a re-import never overwrites an existing author's role."
              }
            },
            "required": [
              "id",
              "name",
              "slug"
            ],
            "description": "Primary/canonical author, or null."
          },
          "authors": {
            "type": "array",
            "description": "Byline authors (incl. the primary), ordered by position.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string"
                },
                "slug": {
                  "type": "string"
                },
                "position": {
                  "type": "integer"
                },
                "avatar_url": {
                  "type": "string",
                  "nullable": true,
                  "format": "uri"
                },
                "role": {
                  "type": "string",
                  "nullable": true,
                  "description": "e.g. \"Head of Content\". Set on author creation only; a re-import never overwrites an existing author's role."
                }
              },
              "required": [
                "id",
                "name",
                "slug",
                "position"
              ]
            }
          },
          "category": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "parent_id": {
                "type": "string",
                "format": "uuid",
                "nullable": true
              }
            },
            "required": [
              "id",
              "name",
              "slug"
            ],
            "description": "Single category, or null."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string"
                },
                "slug": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name",
                "slug"
              ]
            }
          },
          "content": {
            "type": "string",
            "description": "Rendered HTML body."
          },
          "meta": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true
          },
          "json_ld": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "Auto-generated schema.org JSON-LD for this post (per content type: BlogPosting/Article/FAQPage/HowTo/Review/etc.), or null when no markup applies. Ready to embed in a <script type=\"application/ld+json\"> tag. Editor-authored schema_markup overrides the generated value."
          }
        },
        "required": [
          "id",
          "slug",
          "type",
          "title",
          "content"
        ]
      },
      "CmsDeliveryPostSummary": {
        "type": "object",
        "description": "A published post in the headless-delivery LIST response. snake_case (consistent with the API-key v1 CmsPost). Metadata + taxonomy + SEO scalars; the rendered body (content) and meta appear only on the single-post response.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "blog_post",
              "page"
            ]
          },
          "title": {
            "type": "string"
          },
          "excerpt": {
            "type": "string",
            "nullable": true
          },
          "featured_image": {
            "type": "string",
            "nullable": true,
            "format": "uri"
          },
          "featured_image_alt": {
            "type": "string",
            "nullable": true
          },
          "seo_title": {
            "type": "string",
            "nullable": true
          },
          "seo_description": {
            "type": "string",
            "nullable": true
          },
          "focus_keyword": {
            "type": "string",
            "nullable": true
          },
          "canonical_url": {
            "type": "string",
            "nullable": true,
            "format": "uri"
          },
          "schema_markup": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "Editor-authored JSON-LD structured data, if set."
          },
          "og_image": {
            "type": "string",
            "nullable": true,
            "format": "uri"
          },
          "og_title": {
            "type": "string",
            "nullable": true
          },
          "og_description": {
            "type": "string",
            "nullable": true
          },
          "published_at": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "primary_author": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "avatar_url": {
                "type": "string",
                "nullable": true,
                "format": "uri"
              },
              "bio": {
                "type": "string",
                "nullable": true
              },
              "role": {
                "type": "string",
                "nullable": true,
                "description": "e.g. \"Head of Content\". Set on author creation only; a re-import never overwrites an existing author's role."
              }
            },
            "required": [
              "id",
              "name",
              "slug"
            ],
            "description": "Primary/canonical author, or null."
          },
          "authors": {
            "type": "array",
            "description": "Byline authors (incl. the primary), ordered by position.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string"
                },
                "slug": {
                  "type": "string"
                },
                "position": {
                  "type": "integer"
                },
                "avatar_url": {
                  "type": "string",
                  "nullable": true,
                  "format": "uri"
                },
                "role": {
                  "type": "string",
                  "nullable": true,
                  "description": "e.g. \"Head of Content\". Set on author creation only; a re-import never overwrites an existing author's role."
                }
              },
              "required": [
                "id",
                "name",
                "slug",
                "position"
              ]
            }
          },
          "category": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "parent_id": {
                "type": "string",
                "format": "uuid",
                "nullable": true
              }
            },
            "required": [
              "id",
              "name",
              "slug"
            ],
            "description": "Single category, or null."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string"
                },
                "slug": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name",
                "slug"
              ]
            }
          }
        },
        "required": [
          "id",
          "slug",
          "type",
          "title"
        ]
      },
      "TemplateSectionDef": {
        "type": "object",
        "required": [
          "heading",
          "level"
        ],
        "description": "A section definition within a template outline.",
        "properties": {
          "heading": {
            "type": "string",
            "minLength": 1,
            "description": "The section heading text"
          },
          "level": {
            "type": "integer",
            "minimum": 1,
            "maximum": 6,
            "description": "Heading level (1-6)"
          },
          "keyPoints": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "default": [],
            "description": "Key points to cover in this section"
          },
          "suggestedWordCount": {
            "type": "integer",
            "minimum": 0,
            "default": 200,
            "description": "Suggested word count for this section"
          },
          "isRequired": {
            "type": "boolean",
            "default": true,
            "description": "Whether this section is required"
          },
          "generationMode": {
            "type": "string",
            "enum": [
              "ai",
              "manual"
            ],
            "description": "Whether AI generates this section or user provides content"
          }
        }
      },
      "BoilerplateBlock": {
        "type": "object",
        "required": [
          "id",
          "position",
          "content",
          "label"
        ],
        "description": "A reusable content block that can be inserted at specific positions in generated content.",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "description": "Unique identifier for the block"
          },
          "position": {
            "type": "string",
            "enum": [
              "before_section",
              "after_section",
              "header",
              "footer"
            ],
            "description": "Where to insert the block"
          },
          "anchorSectionHeading": {
            "type": "string",
            "description": "Section heading to anchor to (for before_section/after_section positions)"
          },
          "content": {
            "type": "string",
            "maxLength": 50000,
            "description": "The boilerplate content (max 50,000 characters)"
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "description": "Display label for the block"
          }
        }
      },
      "TemplateFieldDefaults": {
        "type": "object",
        "description": "Default field values applied when the template is used.",
        "properties": {
          "targetWordCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Default target word count"
          },
          "metaTitleFormat": {
            "type": "string",
            "description": "Default meta title format"
          },
          "suggestedTone": {
            "type": "string",
            "description": "Default suggested tone"
          },
          "targetLanguage": {
            "type": "string",
            "description": "Default target language"
          },
          "targetCountry": {
            "type": "string",
            "description": "Default target country"
          }
        }
      },
      "Template": {
        "type": "object",
        "description": "A content template defining outline structure, boilerplate blocks, and field defaults.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "content_type": {
            "type": "string",
            "enum": [
              "blog",
              "guide",
              "landing",
              "product",
              "comparison"
            ],
            "nullable": true
          },
          "outline_sections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TemplateSectionDef"
            }
          },
          "section_count": {
            "type": "integer",
            "description": "Number of sections in the outline"
          },
          "total_word_count": {
            "type": "integer",
            "description": "Sum of suggested word counts across all sections"
          },
          "boilerplate_blocks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BoilerplateBlock"
            },
            "nullable": true
          },
          "field_defaults": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TemplateFieldDefaults"
              }
            ],
            "nullable": true
          },
          "source_type": {
            "type": "string",
            "nullable": true,
            "description": "Source from which this template was extracted"
          },
          "is_system": {
            "type": "boolean",
            "description": "Whether this is a system-provided template"
          },
          "is_default": {
            "type": "boolean",
            "description": "Whether this is the default template"
          },
          "is_enabled": {
            "type": "boolean",
            "description": "Whether this template is enabled"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "PaginatedTemplates": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Template"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "ContentOutlineSection": {
        "type": "object",
        "required": [
          "heading",
          "level"
        ],
        "description": "A section in the content outline. Each section represents a heading that will be generated as a content section.",
        "properties": {
          "heading": {
            "type": "string",
            "maxLength": 500,
            "description": "The section heading text"
          },
          "level": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4,
            "description": "Heading level (1=H1, 2=H2, 3=H3, 4=H4)"
          },
          "key_points": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "default": [],
            "description": "Key points to cover in this section"
          },
          "suggested_word_count": {
            "type": "integer",
            "minimum": 0,
            "default": 200,
            "description": "Suggested word count for this section"
          },
          "generation_mode": {
            "type": "string",
            "enum": [
              "ai",
              "manual"
            ],
            "default": "ai",
            "description": "Whether AI generates this section ('ai') or user provides content ('manual')"
          }
        }
      },
      "PaginatedSites": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Site"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "Site": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "domain": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "CreateSiteInput": {
        "type": "object",
        "required": [
          "name",
          "domain"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Display name for the site"
          },
          "domain": {
            "type": "string",
            "description": "Domain name (e.g., example.com). Protocol and trailing slashes are automatically removed."
          },
          "description": {
            "type": "string",
            "description": "Optional description of the site"
          }
        }
      },
      "SiteCreated": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "PaginatedContent": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContentSummary"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "ContentSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "generating",
              "review",
              "published",
              "archived"
            ]
          },
          "word_count": {
            "type": "integer"
          },
          "site_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "is_monitored": {
            "type": "boolean",
            "description": "True when the article is under Content Guard monitoring."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "published_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "scheduled_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When a publish (or plan generation) is scheduled. Null when unscheduled."
          },
          "scheduled_via": {
            "type": "string",
            "nullable": true,
            "description": "What the schedule arms: a publish destination (frase_cms, wordpress), or 'plan' for a content-plan generation promise that is not an armed publish."
          }
        }
      },
      "Content": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "brief_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "site_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "project_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "folder_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "slug": {
            "type": "string",
            "nullable": true
          },
          "type": {
            "type": "string",
            "nullable": true
          },
          "body": {
            "type": "string",
            "nullable": true
          },
          "language": {
            "type": "string",
            "nullable": true,
            "description": "ISO 639-1 language code (e.g., 'en', 'de')"
          },
          "country": {
            "type": "string",
            "nullable": true,
            "description": "ISO 3166-1 country code (e.g., 'US', 'DE')"
          },
          "meta_title": {
            "type": "string",
            "nullable": true
          },
          "meta_description": {
            "type": "string",
            "nullable": true
          },
          "target_keywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "generating",
              "review",
              "published",
              "archived"
            ]
          },
          "word_count": {
            "type": "integer",
            "nullable": true
          },
          "eeat_score": {
            "type": "integer",
            "nullable": true,
            "description": "E-E-A-T score (0-100)"
          },
          "geo_score": {
            "type": "integer",
            "nullable": true,
            "description": "GEO optimization score (0-100)"
          },
          "seo_score": {
            "type": "integer",
            "nullable": true,
            "description": "SEO score (0-100)"
          },
          "quotability_score": {
            "type": "integer",
            "nullable": true,
            "description": "Quotability score (0-100)"
          },
          "ai_citation_score": {
            "type": "integer",
            "nullable": true,
            "description": "AI citation readiness score (0-100)"
          },
          "eeat_breakdown": {
            "$ref": "#/components/schemas/EeatBreakdown"
          },
          "geo_breakdown": {
            "$ref": "#/components/schemas/GeoBreakdown"
          },
          "seo_breakdown": {
            "$ref": "#/components/schemas/SeoBreakdown"
          },
          "featured_image": {
            "type": "string",
            "nullable": true,
            "description": "URL of the featured image"
          },
          "hero_image_prompt": {
            "type": "string",
            "nullable": true,
            "description": "AI prompt used to generate hero image"
          },
          "published_url": {
            "type": "string",
            "nullable": true
          },
          "published_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "is_monitored": {
            "type": "boolean",
            "description": "True when the article is under Content Guard monitoring."
          },
          "monitored_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp monitoring was first enabled for this article."
          },
          "scheduled_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "schema_markup": {
            "type": "object",
            "nullable": true,
            "description": "JSON-LD schema markup"
          },
          "schema_types": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true,
            "description": "Schema types (e.g., 'Article', 'FAQPage')"
          },
          "progress_details": {
            "$ref": "#/components/schemas/ContentProgressDetails"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "EeatBreakdown": {
        "type": "object",
        "nullable": true,
        "description": "E-E-A-T score breakdown",
        "properties": {
          "experience": {
            "type": "number",
            "nullable": true
          },
          "expertise": {
            "type": "number",
            "nullable": true
          },
          "authority": {
            "type": "number",
            "nullable": true
          },
          "trust": {
            "type": "number",
            "nullable": true
          }
        }
      },
      "GeoBreakdown": {
        "type": "object",
        "nullable": true,
        "description": "GEO score breakdown",
        "properties": {
          "quotability": {
            "type": "number",
            "nullable": true
          },
          "structure": {
            "type": "number",
            "nullable": true
          },
          "definitions": {
            "type": "number",
            "nullable": true
          },
          "takeaways": {
            "type": "number",
            "nullable": true
          }
        }
      },
      "SeoBreakdown": {
        "type": "object",
        "nullable": true,
        "description": "SEO score breakdown",
        "properties": {
          "keywords": {
            "type": "number",
            "nullable": true
          },
          "meta": {
            "type": "number",
            "nullable": true
          },
          "structure": {
            "type": "number",
            "nullable": true
          },
          "readability": {
            "type": "number",
            "nullable": true
          }
        }
      },
      "ContentProgressDetails": {
        "type": "object",
        "nullable": true,
        "description": "Progress details for content generation",
        "properties": {
          "phase": {
            "type": "string",
            "enum": [
              "researching",
              "writing",
              "scoring",
              "complete",
              "failed",
              "canceled"
            ]
          },
          "phase_percent": {
            "type": "integer",
            "description": "Progress within current phase (0-100)"
          },
          "substep": {
            "type": "string",
            "description": "Current substep description"
          },
          "current_section": {
            "type": "string"
          },
          "completed_sections": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "word_count": {
            "type": "integer"
          },
          "total_sections": {
            "type": "integer"
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                }
              }
            }
          },
          "citation_count": {
            "type": "integer"
          },
          "error": {
            "type": "string"
          }
        }
      },
      "ContentStatus": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "generating",
              "draft",
              "review",
              "published"
            ]
          },
          "brief_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "brief_topic": {
            "type": "string",
            "nullable": true
          },
          "generation_state": {
            "type": "object",
            "properties": {
              "is_generating": {
                "type": "boolean"
              },
              "is_draft": {
                "type": "boolean"
              },
              "is_review": {
                "type": "boolean"
              },
              "is_published": {
                "type": "boolean"
              },
              "estimated_seconds_remaining": {
                "type": "integer",
                "nullable": true
              }
            }
          },
          "metrics": {
            "type": "object",
            "properties": {
              "word_count": {
                "type": "integer",
                "nullable": true
              }
            }
          },
          "timestamps": {
            "type": "object",
            "properties": {
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "published_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              }
            }
          }
        }
      },
      "ContentExport": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "word_count": {
            "type": "integer"
          },
          "meta": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string"
              },
              "description": {
                "type": "string"
              }
            }
          },
          "target_keywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "brief_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "site_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "project_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "folder_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "language": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "eeat_score": {
            "type": "integer",
            "nullable": true
          },
          "geo_score": {
            "type": "integer",
            "nullable": true
          },
          "seo_score": {
            "type": "integer",
            "nullable": true
          },
          "ai_citation_score": {
            "type": "integer",
            "nullable": true
          },
          "eeat_breakdown": {
            "$ref": "#/components/schemas/EeatBreakdown"
          },
          "geo_breakdown": {
            "$ref": "#/components/schemas/GeoBreakdown"
          },
          "seo_breakdown": {
            "$ref": "#/components/schemas/SeoBreakdown"
          },
          "published_url": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "published_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "scheduled_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "schema_markup": {
            "type": "object",
            "nullable": true
          },
          "schema_types": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "export_format": {
            "type": "string"
          },
          "exported_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PaginatedResearch": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResearchSummary"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "ResearchSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "query": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "language": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "site_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Research": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "query": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "general",
              "topic",
              "competitor",
              "gap",
              "serp"
            ],
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "researching",
              "analyzing",
              "completed",
              "failed"
            ],
            "nullable": true
          },
          "depth": {
            "type": "string",
            "nullable": true
          },
          "summary": {
            "type": "string",
            "nullable": true
          },
          "findings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResearchFinding"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResearchSource"
            }
          },
          "site_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "project_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "language": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "progress": {
            "type": "integer",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "data": {
            "type": "object",
            "nullable": true,
            "description": "Type-specific structured research data. Shape depends on the research type. Null for legacy research sessions.",
            "properties": {
              "keywords": {
                "type": "array",
                "description": "Keywords with metrics (type=general)",
                "items": {
                  "type": "object",
                  "properties": {
                    "keyword": {
                      "type": "string"
                    },
                    "search_volume": {
                      "type": "integer"
                    },
                    "difficulty": {
                      "type": "string",
                      "enum": [
                        "Low",
                        "Medium",
                        "High"
                      ]
                    },
                    "cpc": {
                      "type": "number"
                    },
                    "intent": {
                      "type": "string",
                      "nullable": true
                    },
                    "category": {
                      "type": "string"
                    }
                  }
                }
              },
              "serp_results": {
                "type": "array",
                "description": "SERP competitor analysis (type=general, gap)",
                "items": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "domain": {
                      "type": "string"
                    },
                    "rank": {
                      "type": "integer"
                    },
                    "word_count": {
                      "type": "integer"
                    },
                    "is_own_site": {
                      "type": "boolean"
                    },
                    "is_tracked_competitor": {
                      "type": "boolean"
                    },
                    "headings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string"
                          },
                          "text": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              },
              "evidence": {
                "type": "array",
                "description": "Evidence items (type=general)",
                "items": {
                  "type": "object",
                  "properties": {
                    "text": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "stat",
                        "fact",
                        "quote"
                      ]
                    },
                    "source": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              },
              "sources": {
                "type": "array",
                "description": "Sources found (type=general)",
                "items": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "domain": {
                      "type": "string"
                    }
                  }
                }
              },
              "content_gaps": {
                "type": "array",
                "description": "Content gaps (type=gap, general)",
                "items": {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "impact": {
                      "type": "string",
                      "enum": [
                        "high",
                        "medium",
                        "low"
                      ]
                    },
                    "competitors_covering": {
                      "type": "integer"
                    }
                  }
                }
              },
              "competitors": {
                "type": "array",
                "description": "Competitor analysis (type=competitor)",
                "items": {
                  "type": "object",
                  "properties": {
                    "domain": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "rank": {
                      "type": "integer"
                    },
                    "word_count": {
                      "type": "integer"
                    },
                    "headings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string"
                          },
                          "text": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              },
              "topic_directions": {
                "type": "array",
                "description": "Topic exploration directions (type=topic)",
                "items": {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "angle": {
                      "type": "string"
                    },
                    "estimated_difficulty": {
                      "type": "string",
                      "enum": [
                        "Low",
                        "Medium",
                        "High"
                      ]
                    }
                  }
                }
              },
              "sub_topics": {
                "type": "array",
                "description": "Sub-topic opportunities (type=topic)",
                "items": {
                  "type": "object",
                  "properties": {
                    "topic": {
                      "type": "string"
                    },
                    "relevance": {
                      "type": "number"
                    },
                    "search_volume": {
                      "type": "integer"
                    }
                  }
                }
              },
              "keyword_clusters": {
                "type": "array",
                "description": "Keyword clusters (type=topic)",
                "items": {
                  "type": "object",
                  "properties": {
                    "cluster_name": {
                      "type": "string"
                    },
                    "keywords": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "total_volume": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ResearchFinding": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "content": {
            "type": "string"
          },
          "relevance": {
            "type": "number"
          },
          "source_urls": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "ResearchSource": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "snippet": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          }
        }
      },
      "ResearchExport": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "query": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "depth": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "findings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResearchFinding"
            }
          },
          "topic_clusters": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResearchSource"
            }
          },
          "language": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "export_format": {
            "type": "string"
          },
          "exported_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "IndustryBenchmarkPayload": {
        "type": "object",
        "description": "Composite industry-benchmark payload. Methodology fields (contributingOrgs, sampleSize, sampleWeightSum, outlierSuppressed) are intentionally absent from the wire shape and stripped at the route's stitch boundary regardless of helper-return drift. The `meta` field is additive and not required — older API pods during a rolling deploy may omit it; consumers must tolerate its absence.",
        "required": [
          "context",
          "platforms",
          "geo",
          "shareOfVoice"
        ],
        "properties": {
          "context": {
            "type": "object",
            "required": [
              "vertical",
              "siteId",
              "weekStart"
            ],
            "properties": {
              "vertical": {
                "type": "string",
                "nullable": true,
                "description": "Resolved industry vertical, or null when no vertical can be resolved for the org."
              },
              "siteId": {
                "type": "string",
                "format": "uuid",
                "nullable": true,
                "description": "Echoed site_id; null when site_id was omitted OR silently dropped by the ownership gate."
              },
              "weekStart": {
                "type": "string",
                "format": "date",
                "nullable": true,
                "description": "ISO YYYY-MM-DD week start for the underlying benchmark snapshot."
              }
            }
          },
          "platforms": {
            "type": "array",
            "description": "Per-platform citation rates merged from the org overlay (when include_org=true) and the industry baseline.",
            "items": {
              "type": "object",
              "required": [
                "platform",
                "orgRate",
                "p50",
                "p25",
                "p75"
              ],
              "properties": {
                "platform": {
                  "type": "string",
                  "description": "Canonical platform identifier (e.g. chatgpt, perplexity)."
                },
                "orgRate": {
                  "type": "number",
                  "nullable": true,
                  "description": "Org-aggregate citation rate. Null when include_org=false or no org data."
                },
                "p50": {
                  "type": "number",
                  "description": "Industry-median citation rate."
                },
                "p25": {
                  "type": "number",
                  "description": "Industry 25th-percentile citation rate."
                },
                "p75": {
                  "type": "number",
                  "description": "Industry 75th-percentile citation rate."
                }
              }
            }
          },
          "geo": {
            "type": "object",
            "nullable": true,
            "description": "Geo score comparison. Null when the industry distribution is unavailable or below the k-anon floor.",
            "required": [
              "orgP50",
              "articleCount",
              "industryP50"
            ],
            "properties": {
              "orgP50": {
                "type": "number",
                "nullable": true
              },
              "articleCount": {
                "type": "integer",
                "nullable": true
              },
              "industryP50": {
                "type": "number"
              }
            }
          },
          "shareOfVoice": {
            "type": "object",
            "nullable": true,
            "description": "Share-of-voice. Null when the industry-side k-anon gate dropped all rows.",
            "required": [
              "orgPct",
              "topDomain",
              "topPct"
            ],
            "properties": {
              "orgPct": {
                "type": "number",
                "nullable": true
              },
              "topDomain": {
                "type": "string"
              },
              "topPct": {
                "type": "number"
              }
            }
          },
          "meta": {
            "type": "object",
            "description": "Authoritative readiness signal for cross-surface consumers (UI strip, dashboard hoist, MCP get_industry_benchmark). All three surfaces gate identically on `ready`. `transient: true` means the reason clears as data accrues; `transient: false` is terminal (user action required).",
            "required": [
              "ready",
              "reason",
              "transient"
            ],
            "properties": {
              "ready": {
                "type": "boolean",
                "description": "True when every readiness predicate clears."
              },
              "reason": {
                "type": "string",
                "nullable": true,
                "enum": [
                  "vertical_not_resolved",
                  "card_1_no_share_of_voice",
                  "card_2_insufficient_articles",
                  "card_3_no_medians"
                ],
                "description": "Highest-priority failing predicate, or null when ready=true."
              },
              "transient": {
                "type": "boolean",
                "description": "True when the reason clears as data accrues (no user action required)."
              }
            }
          }
        }
      },
      "CitationFormulaPayload": {
        "type": "object",
        "description": "Single-shape payload for the citation-formula endpoint. Methodology fields (correlationCoef, pValue, sampleSize, id, per-row computedAt) are intentionally absent from the wire shape and stripped at the route's stitch boundary regardless of helper-return drift. The flavor query param controls which fields are populated: flavor=active populates `active` (or null) and leaves `formulas` null; flavor=full populates `formulas` (possibly empty) and leaves `active` null.",
        "required": [
          "context",
          "active",
          "formulas"
        ],
        "properties": {
          "context": {
            "type": "object",
            "required": [
              "vertical",
              "computedAt"
            ],
            "properties": {
              "vertical": {
                "type": "string",
                "nullable": true,
                "description": "Resolved industry vertical, or null when no vertical can be resolved for the org."
              },
              "computedAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "ISO timestamp of the underlying correlate snapshot. For flavor=full, the most-recent row across the returned set."
              }
            }
          },
          "active": {
            "type": "object",
            "nullable": true,
            "description": "Single top recommendation, populated when flavor=active and a positive correlate clears the threshold. Always null when flavor=full.",
            "required": [
              "platform",
              "featureName",
              "featureLabel",
              "citationLiftPct"
            ],
            "properties": {
              "platform": {
                "type": "string",
                "description": "Canonical platform identifier (e.g. chatgpt, perplexity)."
              },
              "featureName": {
                "type": "string",
                "description": "Machine-readable feature identifier from the cron-written table."
              },
              "featureLabel": {
                "type": "string",
                "description": "Human-readable label for the feature (mapped from featureName)."
              },
              "citationLiftPct": {
                "type": "number",
                "nullable": true,
                "description": "Citation-rate lift percentage associated with the feature."
              }
            }
          },
          "formulas": {
            "type": "array",
            "nullable": true,
            "description": "Ranked list of positive correlates above the sample-size floor, populated when flavor=full. Always null when flavor=active. May be empty for verticals with no positive correlates yet.",
            "items": {
              "type": "object",
              "required": [
                "platform",
                "featureName",
                "featureLabel",
                "citationLiftPct"
              ],
              "properties": {
                "platform": {
                  "type": "string"
                },
                "featureName": {
                  "type": "string"
                },
                "featureLabel": {
                  "type": "string"
                },
                "citationLiftPct": {
                  "type": "number",
                  "nullable": true
                }
              }
            }
          }
        }
      },
      "AIVisibilityOverview": {
        "type": "object",
        "properties": {
          "overview": {
            "type": "object",
            "properties": {
              "total_prompts": {
                "type": "integer"
              },
              "avg_visibility_score": {
                "type": "number",
                "nullable": true,
                "description": "Average visibility score over the prompts measured in the window: each prompt's latest measured answer per platform, averaged per prompt and then across prompts. Null when no prompt was measured in the window. Changed 2026-09-19: previously each prompt's cached latest score, regardless of window."
              },
              "share_of_voice": {
                "type": "number",
                "nullable": true,
                "description": "Brand share of voice over the window's measured answers (brand presence over brand plus competitor presence), one decimal. Null when no prompt was measured in the window (documented 2026-09-19; previously undocumented and 0 with nothing measured). Changed 2026-10-01: a name that is an ordinary word or a place, or is made only of them (\"Landing\", \"Home Instead\", \"Visit Mobile\"), counts only where the answer writes it as a name, every significant word capitalised, or links the entity's own site; answers read from this date on are counted this way, and a re-read applies it to earlier days."
              },
              "total_checks": {
                "type": "integer"
              },
              "total_mentions": {
                "type": "integer"
              },
              "total_citations": {
                "type": "integer"
              },
              "period_days": {
                "type": "integer"
              }
            }
          },
          "platform_breakdown": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "platform": {
                  "type": "string"
                },
                "checks": {
                  "type": "integer"
                },
                "mentions": {
                  "type": "integer"
                },
                "citations": {
                  "type": "integer"
                },
                "mention_rate": {
                  "type": "integer",
                  "description": "Mention rate as percentage (0-100)"
                },
                "citation_rate": {
                  "type": "integer",
                  "description": "Citation rate as percentage (0-100)"
                }
              }
            }
          },
          "prompts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "prompt": {
                  "type": "string"
                },
                "category": {
                  "type": "string",
                  "nullable": true
                },
                "brand_name": {
                  "type": "string"
                },
                "platforms": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "visibility_score": {
                  "type": "number",
                  "nullable": true,
                  "description": "The prompt's visibility score over the window: its latest measured answer per platform, averaged. Null when the prompt has no measured answer in the window. Changed 2026-09-19: previously the prompt's cached latest score (one answer on one platform, regardless of window); the overview's avg_visibility_score is the mean of these."
                },
                "is_cited": {
                  "type": "boolean"
                },
                "is_visible": {
                  "type": "boolean"
                },
                "status": {
                  "type": "string",
                  "description": "Verdict of the prompt's latest measured answer per platform. `unmeasured` (added 2026-09-18): no measured answer in the window - never analyzed, failed, or marked unscoreable; `visibility_score` is null then.",
                  "enum": [
                    "cited",
                    "visible",
                    "not_visible",
                    "unmeasured"
                  ]
                },
                "last_tracked_at": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true
                },
                "created_at": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "daily_trend": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "format": "date"
                },
                "visibility_score": {
                  "type": "number",
                  "nullable": true
                },
                "total_checks": {
                  "type": "integer",
                  "nullable": true
                },
                "mentions": {
                  "type": "integer",
                  "nullable": true
                },
                "citations": {
                  "type": "integer",
                  "nullable": true
                }
              }
            }
          }
        }
      },
      "SERPAnalysis": {
        "type": "object",
        "properties": {
          "keyword": {
            "type": "string"
          },
          "search_parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string"
              },
              "country_code": {
                "type": "string"
              },
              "language_code": {
                "type": "string"
              },
              "num_results": {
                "type": "integer"
              }
            }
          },
          "search_info": {
            "type": "object",
            "properties": {
              "total_results": {
                "type": "integer",
                "nullable": true
              },
              "time_taken": {
                "type": "number",
                "nullable": true
              }
            }
          },
          "ai_overview": {
            "type": "object",
            "nullable": true,
            "properties": {
              "text": {
                "type": "string"
              },
              "sources": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    },
                    "snippet": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "organic_results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "position": {
                  "type": "integer"
                },
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "snippet": {
                  "type": "string"
                }
              }
            }
          },
          "people_also_ask": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "position": {
                  "type": "integer"
                },
                "question": {
                  "type": "string"
                },
                "snippet": {
                  "type": "string",
                  "nullable": true
                },
                "source_url": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "related_searches": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "WebhookWithSecret": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "is_active": {
            "type": "boolean"
          },
          "secret": {
            "type": "string",
            "description": "Only returned on creation. Store securely."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "JobStatus": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "type": {
            "type": "string",
            "enum": [
              "audit",
              "research",
              "content",
              "brief",
              "optimization",
              "atomization"
            ]
          },
          "status": {
            "type": "string"
          },
          "progress": {
            "type": "integer"
          },
          "error": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time"
          },
          "metadata": {
            "type": "object"
          }
        }
      },
      "Rule": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "condition_type": {
            "type": "string",
            "enum": [
              "score_threshold",
              "term_compliance",
              "verify_chips",
              "word_count",
              "meta_required",
              "link_count",
              "section_required",
              "regex_pattern",
              "competitor_filter"
            ]
          },
          "config": {
            "type": "object",
            "description": "Rule configuration object, structure varies by condition_type"
          },
          "severity": {
            "type": "string",
            "enum": [
              "error",
              "warning",
              "info"
            ]
          },
          "fix_hint": {
            "type": "string",
            "nullable": true
          },
          "is_system": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "RuleDetail": {
        "type": "object",
        "description": "Rule with additional detail fields including updated_at",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "condition_type": {
            "type": "string",
            "enum": [
              "score_threshold",
              "term_compliance",
              "verify_chips",
              "word_count",
              "meta_required",
              "link_count",
              "section_required",
              "regex_pattern",
              "competitor_filter"
            ]
          },
          "config": {
            "type": "object",
            "description": "Rule configuration object, structure varies by condition_type"
          },
          "severity": {
            "type": "string",
            "enum": [
              "error",
              "warning",
              "info"
            ]
          },
          "fix_hint": {
            "type": "string",
            "nullable": true
          },
          "is_system": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "PaginatedRules": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Rule"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "Playbook": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "step_count": {
            "type": "integer"
          },
          "estimated_minutes": {
            "type": "integer",
            "nullable": true
          },
          "is_system": {
            "type": "boolean"
          },
          "is_enabled": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "PlaybookSummary": {
        "type": "object",
        "description": "Playbook as returned in list responses",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "step_count": {
            "type": "integer"
          },
          "estimated_minutes": {
            "type": "integer",
            "nullable": true
          },
          "is_system": {
            "type": "boolean"
          },
          "is_enabled": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer"
          },
          "page_size": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "has_more": {
            "type": "boolean"
          }
        }
      },
      "RuleSetRuleSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "condition_type": {
            "type": "string"
          },
          "severity": {
            "type": "string"
          },
          "sort_order": {
            "type": "integer"
          }
        }
      },
      "RuleSetRuleDetail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "condition_type": {
            "type": "string"
          },
          "config": {
            "type": "object",
            "nullable": true
          },
          "severity": {
            "type": "string"
          },
          "fix_hint": {
            "type": "string",
            "nullable": true
          },
          "is_system": {
            "type": "boolean"
          },
          "sort_order": {
            "type": "integer"
          }
        }
      },
      "RuleSetSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "is_system": {
            "type": "boolean"
          },
          "is_enabled": {
            "type": "boolean"
          },
          "rule_count": {
            "type": "integer"
          },
          "rules": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RuleSetRuleSummary"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "RuleSetDetail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "is_system": {
            "type": "boolean"
          },
          "is_enabled": {
            "type": "boolean"
          },
          "rule_count": {
            "type": "integer"
          },
          "rules": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RuleSetRuleDetail"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "PaginatedRuleSets": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RuleSetSummary"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "Comment": {
        "type": "object",
        "description": "A comment attached to a content article. Human-authored comments have `author.is_system_user = false`; AI-authored comments have `author.is_system_user = true` and populate `ai_suggestion`. Clients rebuild threads via `parent_comment_id` / `root_comment_id`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "body": {
            "type": "string",
            "description": "Markdown body. For AI comments, the AI-metadata prefix is already stripped."
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "resolved"
            ]
          },
          "selection_start": {
            "type": "integer",
            "nullable": true,
            "description": "Editor position (ProseMirror coordinates) where the anchored selection begins. AI comments created via the public `POST /content/{id}/ai-comments` endpoint return `null` here — use `selection_text` to locate the anchor."
          },
          "selection_end": {
            "type": "integer",
            "nullable": true,
            "description": "Editor position where the anchored selection ends. See `selection_start` for nullability notes."
          },
          "selection_text": {
            "type": "string",
            "nullable": true,
            "description": "Verbatim text excerpt the comment is anchored to."
          },
          "content_version": {
            "type": "integer",
            "nullable": true
          },
          "parent_comment_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "root_comment_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "mentioned_user_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "author": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "nullable": true
              },
              "name": {
                "type": "string",
                "nullable": true
              },
              "email": {
                "type": "string",
                "nullable": true
              },
              "avatar_url": {
                "type": "string",
                "nullable": true
              },
              "is_system_user": {
                "type": "boolean"
              }
            }
          },
          "ai_suggestion": {
            "type": "object",
            "nullable": true,
            "description": "Present on AI-authored comments. `suggested_text` is the replacement copy that `POST /content/{id}/ai-comments/{commentId}/apply` will splice into the article body.",
            "properties": {
              "category": {
                "type": "string",
                "enum": [
                  "structure",
                  "clarity",
                  "seo",
                  "governance",
                  "engagement",
                  "authority"
                ]
              },
              "suggested_text": {
                "type": "string"
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "resolved_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "resolved_by_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          }
        }
      },
      "RequestedAiComment": {
        "type": "object",
        "description": "A single AI suggestion comment created by `POST /content/{id}/ai-comments`. Use `id` with the `apply` endpoint or with `PATCH /comments/{id}`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "category": {
            "type": "string",
            "enum": [
              "structure",
              "clarity",
              "seo",
              "governance",
              "engagement",
              "authority"
            ]
          },
          "section": {
            "type": "string"
          },
          "quote": {
            "type": "string"
          },
          "suggestion": {
            "type": "string"
          },
          "suggested_text": {
            "type": "string",
            "nullable": true
          },
          "selection_anchored": {
            "type": "boolean",
            "description": "True when `quote` was found in the draft's plain-text projection and the comment will be applyable. False means the quote couldn't be located — apply will 409 with `target_text_not_found`."
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "param": {
                "type": "string"
              },
              "doc_url": {
                "type": "string"
              }
            }
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "CmsResearchSessionEmbed": {
        "type": "object",
        "description": "Read-only research-provenance embed attached to a CMS post via `?include=research`. Derived from the research session the post's content was generated from; always organization-scoped.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Research session id"
          },
          "query": {
            "type": "string",
            "nullable": true,
            "description": "Research session title / query"
          },
          "serp_competitors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "domain": {
                  "type": "string"
                },
                "rank": {
                  "type": "number"
                }
              }
            }
          },
          "search_intent": {
            "type": "object",
            "nullable": true,
            "properties": {
              "intent_type": {
                "type": "string"
              },
              "confidence": {
                "type": "number"
              }
            }
          },
          "questions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "question": {
                  "type": "string"
                },
                "source": {
                  "type": "string"
                }
              }
            }
          },
          "content_gaps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "impact": {
                  "type": "string"
                }
              }
            }
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "CmsPost": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "site_id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "blog_post",
              "page"
            ]
          },
          "title": {
            "type": "string"
          },
          "content": {
            "type": "string",
            "description": "HTML content"
          },
          "excerpt": {
            "type": "string",
            "nullable": true
          },
          "featured_image": {
            "type": "string",
            "format": "uri",
            "nullable": true
          },
          "seo_title": {
            "type": "string",
            "nullable": true
          },
          "seo_description": {
            "type": "string",
            "nullable": true
          },
          "focus_keyword": {
            "type": "string",
            "nullable": true
          },
          "canonical_url": {
            "type": "string",
            "format": "uri",
            "nullable": true
          },
          "schema_markup": {
            "type": "object",
            "description": "JSON-LD structured data for the post. Must include `@context` and `@type`. Additional properties depend on the chosen schema type. See [schema.org](https://schema.org) for full type definitions.",
            "properties": {
              "@context": {
                "type": "string",
                "default": "https://schema.org",
                "description": "Schema.org context URL. Almost always `https://schema.org`."
              },
              "@type": {
                "type": "string",
                "description": "The schema.org type for this content.",
                "enum": [
                  "Article",
                  "BlogPosting",
                  "NewsArticle",
                  "FAQPage",
                  "HowTo",
                  "TechArticle",
                  "WebPage"
                ]
              },
              "headline": {
                "type": "string",
                "description": "The headline of the article. Recommended for Article, BlogPosting, NewsArticle.",
                "maxLength": 110
              },
              "description": {
                "type": "string",
                "description": "A short description or summary of the content."
              },
              "author": {
                "oneOf": [
                  {
                    "type": "object",
                    "description": "Author as a Person or Organization.",
                    "properties": {
                      "@type": {
                        "type": "string",
                        "enum": [
                          "Person",
                          "Organization"
                        ]
                      },
                      "name": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      }
                    }
                  },
                  {
                    "type": "array",
                    "description": "Multiple authors.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "@type": {
                          "type": "string",
                          "enum": [
                            "Person",
                            "Organization"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  }
                ]
              },
              "datePublished": {
                "type": "string",
                "format": "date",
                "description": "Original publication date in ISO 8601 format (e.g., `2026-04-16`)."
              },
              "dateModified": {
                "type": "string",
                "format": "date",
                "description": "Last modification date in ISO 8601 format."
              },
              "image": {
                "oneOf": [
                  {
                    "type": "string",
                    "format": "uri"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "@type": {
                        "type": "string",
                        "enum": [
                          "ImageObject"
                        ]
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      },
                      "width": {
                        "type": "integer"
                      },
                      "height": {
                        "type": "integer"
                      }
                    }
                  }
                ],
                "description": "Primary image. Can be a URL string or an ImageObject."
              },
              "publisher": {
                "type": "object",
                "description": "The publisher of the content.",
                "properties": {
                  "@type": {
                    "type": "string",
                    "enum": [
                      "Organization"
                    ]
                  },
                  "name": {
                    "type": "string"
                  },
                  "logo": {
                    "type": "object",
                    "properties": {
                      "@type": {
                        "type": "string",
                        "enum": [
                          "ImageObject"
                        ]
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      }
                    }
                  }
                }
              },
              "mainEntity": {
                "description": "Primary entity of the page. Used by FAQPage (array of Question) and HowTo (HowToStep array).",
                "oneOf": [
                  {
                    "type": "array",
                    "description": "For FAQPage: array of Question objects.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "@type": {
                          "type": "string",
                          "enum": [
                            "Question"
                          ]
                        },
                        "name": {
                          "type": "string",
                          "description": "The question text."
                        },
                        "acceptedAnswer": {
                          "type": "object",
                          "properties": {
                            "@type": {
                              "type": "string",
                              "enum": [
                                "Answer"
                              ]
                            },
                            "text": {
                              "type": "string",
                              "description": "The answer text."
                            }
                          }
                        }
                      }
                    }
                  },
                  {
                    "type": "object"
                  }
                ]
              },
              "step": {
                "type": "array",
                "description": "For HowTo: ordered list of steps.",
                "items": {
                  "type": "object",
                  "properties": {
                    "@type": {
                      "type": "string",
                      "enum": [
                        "HowToStep"
                      ]
                    },
                    "name": {
                      "type": "string",
                      "description": "Step title."
                    },
                    "text": {
                      "type": "string",
                      "description": "Step instructions."
                    },
                    "image": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            },
            "additionalProperties": true,
            "nullable": true,
            "examples": [
              {
                "@context": "https://schema.org",
                "@type": "BlogPosting",
                "headline": "How to Optimize Content for SEO",
                "description": "A comprehensive guide to on-page SEO optimization.",
                "author": {
                  "@type": "Person",
                  "name": "Jane Smith",
                  "url": "https://example.com/jane"
                },
                "publisher": {
                  "@type": "Organization",
                  "name": "Acme Inc.",
                  "logo": {
                    "@type": "ImageObject",
                    "url": "https://example.com/logo.png"
                  }
                },
                "datePublished": "2026-04-16",
                "dateModified": "2026-04-16",
                "image": "https://example.com/images/seo-guide.jpg"
              },
              {
                "@context": "https://schema.org",
                "@type": "FAQPage",
                "mainEntity": [
                  {
                    "@type": "Question",
                    "name": "What is SEO?",
                    "acceptedAnswer": {
                      "@type": "Answer",
                      "text": "SEO stands for Search Engine Optimization, the practice of improving a website's visibility in search results."
                    }
                  },
                  {
                    "@type": "Question",
                    "name": "How long does SEO take?",
                    "acceptedAnswer": {
                      "@type": "Answer",
                      "text": "SEO typically takes 3-6 months to show significant results."
                    }
                  }
                ]
              },
              {
                "@context": "https://schema.org",
                "@type": "HowTo",
                "name": "How to Write a Content Brief",
                "description": "Step-by-step guide to creating an effective content brief.",
                "step": [
                  {
                    "@type": "HowToStep",
                    "name": "Research keywords",
                    "text": "Use a keyword research tool to find relevant terms."
                  },
                  {
                    "@type": "HowToStep",
                    "name": "Analyze competitors",
                    "text": "Review top-ranking pages for your target keyword."
                  },
                  {
                    "@type": "HowToStep",
                    "name": "Define structure",
                    "text": "Create an outline with headings and subheadings."
                  }
                ]
              }
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "published",
              "scheduled"
            ]
          },
          "published_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "meta": {
            "type": "object",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "primary_author": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "avatar_url": {
                "type": "string",
                "nullable": true,
                "format": "uri"
              },
              "bio": {
                "type": "string",
                "nullable": true
              },
              "role": {
                "type": "string",
                "nullable": true,
                "description": "e.g. \"Head of Content\". Set on author creation only; a re-import never overwrites an existing author's role."
              }
            },
            "required": [
              "id",
              "name",
              "slug"
            ],
            "description": "Primary/canonical author, or null."
          },
          "authors": {
            "type": "array",
            "description": "Byline authors (incl. the primary), ordered by position.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string"
                },
                "slug": {
                  "type": "string"
                },
                "position": {
                  "type": "integer"
                },
                "avatar_url": {
                  "type": "string",
                  "nullable": true,
                  "format": "uri"
                },
                "role": {
                  "type": "string",
                  "nullable": true,
                  "description": "e.g. \"Head of Content\". Set on author creation only; a re-import never overwrites an existing author's role."
                }
              },
              "required": [
                "id",
                "name",
                "slug",
                "position"
              ]
            }
          },
          "category": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "parent_id": {
                "type": "string",
                "format": "uuid",
                "nullable": true
              }
            },
            "required": [
              "id",
              "name",
              "slug"
            ],
            "description": "Single category, or null."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string"
                },
                "slug": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name",
                "slug"
              ]
            }
          }
        }
      },
      "CmsPostInput": {
        "type": "object",
        "required": [
          "site_id",
          "title",
          "content"
        ],
        "properties": {
          "site_id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string",
            "maxLength": 500
          },
          "content": {
            "type": "string",
            "maxLength": 512000,
            "description": "HTML content (max 500KB)"
          },
          "slug": {
            "type": "string",
            "description": "URL slug. Auto-generated from title if omitted."
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "published",
              "scheduled"
            ],
            "default": "draft"
          },
          "type": {
            "type": "string",
            "enum": [
              "blog_post",
              "page"
            ],
            "default": "blog_post"
          },
          "excerpt": {
            "type": "string",
            "maxLength": 2000
          },
          "featured_image": {
            "type": "string",
            "format": "uri",
            "description": "Must be HTTPS"
          },
          "seo_title": {
            "type": "string",
            "maxLength": 200
          },
          "seo_description": {
            "type": "string",
            "maxLength": 500
          },
          "focus_keyword": {
            "type": "string"
          },
          "canonical_url": {
            "type": "string",
            "format": "uri",
            "description": "Must be HTTPS"
          },
          "published_at": {
            "type": "string",
            "format": "date-time"
          },
          "schema_markup": {
            "type": "object",
            "description": "JSON-LD structured data for the post. Must include `@context` and `@type`. Additional properties depend on the chosen schema type. See [schema.org](https://schema.org) for full type definitions.",
            "properties": {
              "@context": {
                "type": "string",
                "default": "https://schema.org",
                "description": "Schema.org context URL. Almost always `https://schema.org`."
              },
              "@type": {
                "type": "string",
                "description": "The schema.org type for this content.",
                "enum": [
                  "Article",
                  "BlogPosting",
                  "NewsArticle",
                  "FAQPage",
                  "HowTo",
                  "TechArticle",
                  "WebPage"
                ]
              },
              "headline": {
                "type": "string",
                "description": "The headline of the article. Recommended for Article, BlogPosting, NewsArticle.",
                "maxLength": 110
              },
              "description": {
                "type": "string",
                "description": "A short description or summary of the content."
              },
              "author": {
                "oneOf": [
                  {
                    "type": "object",
                    "description": "Author as a Person or Organization.",
                    "properties": {
                      "@type": {
                        "type": "string",
                        "enum": [
                          "Person",
                          "Organization"
                        ]
                      },
                      "name": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      }
                    }
                  },
                  {
                    "type": "array",
                    "description": "Multiple authors.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "@type": {
                          "type": "string",
                          "enum": [
                            "Person",
                            "Organization"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  }
                ]
              },
              "datePublished": {
                "type": "string",
                "format": "date",
                "description": "Original publication date in ISO 8601 format (e.g., `2026-04-16`)."
              },
              "dateModified": {
                "type": "string",
                "format": "date",
                "description": "Last modification date in ISO 8601 format."
              },
              "image": {
                "oneOf": [
                  {
                    "type": "string",
                    "format": "uri"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "@type": {
                        "type": "string",
                        "enum": [
                          "ImageObject"
                        ]
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      },
                      "width": {
                        "type": "integer"
                      },
                      "height": {
                        "type": "integer"
                      }
                    }
                  }
                ],
                "description": "Primary image. Can be a URL string or an ImageObject."
              },
              "publisher": {
                "type": "object",
                "description": "The publisher of the content.",
                "properties": {
                  "@type": {
                    "type": "string",
                    "enum": [
                      "Organization"
                    ]
                  },
                  "name": {
                    "type": "string"
                  },
                  "logo": {
                    "type": "object",
                    "properties": {
                      "@type": {
                        "type": "string",
                        "enum": [
                          "ImageObject"
                        ]
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      }
                    }
                  }
                }
              },
              "mainEntity": {
                "description": "Primary entity of the page. Used by FAQPage (array of Question) and HowTo (HowToStep array).",
                "oneOf": [
                  {
                    "type": "array",
                    "description": "For FAQPage: array of Question objects.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "@type": {
                          "type": "string",
                          "enum": [
                            "Question"
                          ]
                        },
                        "name": {
                          "type": "string",
                          "description": "The question text."
                        },
                        "acceptedAnswer": {
                          "type": "object",
                          "properties": {
                            "@type": {
                              "type": "string",
                              "enum": [
                                "Answer"
                              ]
                            },
                            "text": {
                              "type": "string",
                              "description": "The answer text."
                            }
                          }
                        }
                      }
                    }
                  },
                  {
                    "type": "object"
                  }
                ]
              },
              "step": {
                "type": "array",
                "description": "For HowTo: ordered list of steps.",
                "items": {
                  "type": "object",
                  "properties": {
                    "@type": {
                      "type": "string",
                      "enum": [
                        "HowToStep"
                      ]
                    },
                    "name": {
                      "type": "string",
                      "description": "Step title."
                    },
                    "text": {
                      "type": "string",
                      "description": "Step instructions."
                    },
                    "image": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            },
            "additionalProperties": true
          },
          "meta": {
            "type": "object"
          },
          "related_post_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "maxItems": 3,
            "description": "Ordered curated related-post ids (max 3). Every id must be a PUBLISHED blog post on the same site as this post; the list is deduplicated and the post's own id is dropped. More than 3 ids is rejected with a 400. On update, the array REPLACES the existing set; pass [] to clear. Failures to apply are returned as warnings inside data, not an error."
          }
        }
      },
      "CmsPostUpdateInput": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "maxLength": 500
          },
          "content": {
            "type": "string",
            "maxLength": 512000
          },
          "slug": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "blog_post",
              "page"
            ]
          },
          "excerpt": {
            "type": "string",
            "maxLength": 2000
          },
          "featured_image": {
            "type": "string",
            "format": "uri"
          },
          "seo_title": {
            "type": "string",
            "maxLength": 200
          },
          "seo_description": {
            "type": "string",
            "maxLength": 500
          },
          "focus_keyword": {
            "type": "string"
          },
          "canonical_url": {
            "type": "string",
            "format": "uri"
          },
          "schema_markup": {
            "type": "object",
            "description": "JSON-LD structured data for the post. Must include `@context` and `@type`. Additional properties depend on the chosen schema type. See [schema.org](https://schema.org) for full type definitions.",
            "properties": {
              "@context": {
                "type": "string",
                "default": "https://schema.org",
                "description": "Schema.org context URL. Almost always `https://schema.org`."
              },
              "@type": {
                "type": "string",
                "description": "The schema.org type for this content.",
                "enum": [
                  "Article",
                  "BlogPosting",
                  "NewsArticle",
                  "FAQPage",
                  "HowTo",
                  "TechArticle",
                  "WebPage"
                ]
              },
              "headline": {
                "type": "string",
                "description": "The headline of the article. Recommended for Article, BlogPosting, NewsArticle.",
                "maxLength": 110
              },
              "description": {
                "type": "string",
                "description": "A short description or summary of the content."
              },
              "author": {
                "oneOf": [
                  {
                    "type": "object",
                    "description": "Author as a Person or Organization.",
                    "properties": {
                      "@type": {
                        "type": "string",
                        "enum": [
                          "Person",
                          "Organization"
                        ]
                      },
                      "name": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      }
                    }
                  },
                  {
                    "type": "array",
                    "description": "Multiple authors.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "@type": {
                          "type": "string",
                          "enum": [
                            "Person",
                            "Organization"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  }
                ]
              },
              "datePublished": {
                "type": "string",
                "format": "date",
                "description": "Original publication date in ISO 8601 format (e.g., `2026-04-16`)."
              },
              "dateModified": {
                "type": "string",
                "format": "date",
                "description": "Last modification date in ISO 8601 format."
              },
              "image": {
                "oneOf": [
                  {
                    "type": "string",
                    "format": "uri"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "@type": {
                        "type": "string",
                        "enum": [
                          "ImageObject"
                        ]
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      },
                      "width": {
                        "type": "integer"
                      },
                      "height": {
                        "type": "integer"
                      }
                    }
                  }
                ],
                "description": "Primary image. Can be a URL string or an ImageObject."
              },
              "publisher": {
                "type": "object",
                "description": "The publisher of the content.",
                "properties": {
                  "@type": {
                    "type": "string",
                    "enum": [
                      "Organization"
                    ]
                  },
                  "name": {
                    "type": "string"
                  },
                  "logo": {
                    "type": "object",
                    "properties": {
                      "@type": {
                        "type": "string",
                        "enum": [
                          "ImageObject"
                        ]
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      }
                    }
                  }
                }
              },
              "mainEntity": {
                "description": "Primary entity of the page. Used by FAQPage (array of Question) and HowTo (HowToStep array).",
                "oneOf": [
                  {
                    "type": "array",
                    "description": "For FAQPage: array of Question objects.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "@type": {
                          "type": "string",
                          "enum": [
                            "Question"
                          ]
                        },
                        "name": {
                          "type": "string",
                          "description": "The question text."
                        },
                        "acceptedAnswer": {
                          "type": "object",
                          "properties": {
                            "@type": {
                              "type": "string",
                              "enum": [
                                "Answer"
                              ]
                            },
                            "text": {
                              "type": "string",
                              "description": "The answer text."
                            }
                          }
                        }
                      }
                    }
                  },
                  {
                    "type": "object"
                  }
                ]
              },
              "step": {
                "type": "array",
                "description": "For HowTo: ordered list of steps.",
                "items": {
                  "type": "object",
                  "properties": {
                    "@type": {
                      "type": "string",
                      "enum": [
                        "HowToStep"
                      ]
                    },
                    "name": {
                      "type": "string",
                      "description": "Step title."
                    },
                    "text": {
                      "type": "string",
                      "description": "Step instructions."
                    },
                    "image": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            },
            "additionalProperties": true
          },
          "meta": {
            "type": "object"
          },
          "related_post_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "maxItems": 3,
            "description": "Ordered curated related-post ids (max 3). Every id must be a PUBLISHED blog post on the same site as this post; the list is deduplicated and the post's own id is dropped. More than 3 ids is rejected with a 400. On update, the array REPLACES the existing set; pass [] to clear. Failures to apply are returned as warnings inside data, not an error."
          }
        }
      },
      "CmsImportJob": {
        "type": "object",
        "properties": {
          "job_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "processing",
              "completed",
              "failed"
            ]
          },
          "site_id": {
            "type": "string",
            "format": "uuid"
          },
          "posts_queued": {
            "type": "integer"
          },
          "posts_succeeded": {
            "type": "integer"
          },
          "posts_failed": {
            "type": "integer"
          },
          "posts_skipped": {
            "type": "integer"
          },
          "errors": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "slug": {
                  "type": "string"
                },
                "error": {
                  "type": "string"
                }
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Authentication failed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "type": "authentication_error",
                "code": "invalid_api_key",
                "message": "Invalid API key. Check that you are using the correct key.",
                "doc_url": "https://docs.frase.io/api/errors#invalid_api_key"
              },
              "request_id": "req_abc123"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "type": "invalid_request_error",
                "code": "resource_not_found",
                "message": "The requested resource was not found.",
                "doc_url": "https://docs.frase.io/api/errors#resource_not_found"
              },
              "request_id": "req_abc123"
            }
          }
        }
      },
      "ValidationError": {
        "description": "Validation failed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "type": "invalid_request_error",
                "code": "validation_error",
                "message": "The request body is invalid.",
                "param": "prompt_text",
                "doc_url": "https://docs.frase.io/api/errors#validation_error"
              },
              "request_id": "req_abc123"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden - action not allowed on this resource",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "type": "invalid_request_error",
                "code": "forbidden",
                "message": "System rules cannot be modified.",
                "doc_url": "https://docs.frase.io/api/errors#forbidden"
              },
              "request_id": "req_abc123"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until rate limit resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "type": "rate_limit_error",
                "code": "rate_limit_exceeded",
                "message": "Rate limit exceeded. Please retry after 60 seconds.",
                "doc_url": "https://docs.frase.io/api/errors#rate_limit_exceeded"
              },
              "request_id": "req_abc123"
            }
          }
        }
      },
      "ActivePromptLimitExceeded": {
        "description": "Org-wide active-prompt cap reached (ai_prompt_limit_exceeded). Returned when creating an active prompt, or when a PATCH transitions a prompt's status to active. The cap counts concurrently active prompts, not monthly usage. Pause a prompt to free a slot, or upgrade your plan.",
        "headers": {
          "X-Active-Limit": {
            "schema": {
              "type": "integer"
            },
            "description": "Your plan's active-prompt cap"
          },
          "X-Active-Used": {
            "schema": {
              "type": "integer"
            },
            "description": "Prompts currently active"
          },
          "X-Active-Remaining": {
            "schema": {
              "type": "integer"
            },
            "description": "Active-prompt slots remaining"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "type": "rate_limit_error",
                "code": "ai_prompt_limit_exceeded",
                "message": "You're at your plan's max active prompts (3). Pause one to add a new one, or upgrade your plan.",
                "doc_url": "https://docs.frase.io/api/errors#ai_prompt_limit_exceeded"
              },
              "request_id": "req_abc123"
            }
          }
        }
      }
    }
  }
}
