{
  "openapi": "3.1.0",
  "info": {
    "title": "Beket API",
    "version": "0.1.0",
    "description": "Programmatic access to AEO/GEO audits: create a target, configure it, run a measurement, and\nread the results.\n\n**This API is in beta.** The documented surface is stable enough to build against, and we\npublish every change, but shapes may still move. Pin nothing you cannot adjust.\n\n## Authenticating\n\nEvery endpoint except `GET /openapi.json` requires an API key, sent as a bearer token:\n\n```\nAuthorization: Bearer bkt_your_key_here\n```\n\nKeys are created by an organization **owner** in **Settings → Developer & AI → API keys**, and\neach one is scoped to the organization that created it — a key never sees another\norganization's data. The raw key is shown once, at creation.\n\nWhat a key may do:\n\n- **Read-only or read+write.** A read-only key receives **403** on any request that is not a\n  GET, HEAD, or OPTIONS.\n- **Never more than an editor.** A key acts with its creator's current role, capped at editor.\n  If the creator is later made a viewer, the key's writes receive 403. Owner-only surfaces\n  (API keys, billing, members, organization settings) answer 403 to every key, so they are not\n  in this document.\n- **Paid plans for everything but Zapier.** A key belonging to a free-plan organization reaches\n  only `/zapier/*` and `POST /audits/{auditId}/prompts/bulk`; any other path is rejected\n  with **402** before it reaches any handler.\n\n## Rate limits\n\nThe namespaces polled on a schedule we do not control carry a per-key limit. Beyond it the API\nanswers **429**; back off and retry after the window.\n\n- `/zapier/*`: 120 requests per minute per key\n- `/looker/*`: 120 requests per minute per key\n\n## Response shape\n\nEvery endpoint answers with the same envelope:\n\n```json\n{ \"success\": true, \"data\": { } }\n```\n\nFailures carry the same envelope with `success: false` and an `error` object:\n\n```json\n{ \"success\": false, \"error\": { \"message\": \"...\", \"type\": \"NotFoundError\" } }\n```\n\n`GET /openapi.json` is the one exception — it returns the document itself, unwrapped, because\nstandard OpenAPI tooling cannot read a wrapped one.\n\n## Asynchronous work\n\nMeasuring is not instant. Endpoints that start work answer **202** and hand back a status you\npoll. `GET /audits/{auditId}/run` returns `retryAfterMs` — use it rather than a fixed\ninterval; polling faster does not make a run finish sooner.\n\n## Payload size\n\nSome reads are large by nature, and transfer is a real cost on both sides. Where a bounded\nalternative exists, the endpoint's description names it. In short: poll\n`GET /audits/{auditId}/snapshots`, which is small, and fetch the full report only when a new\nsnapshot appears.\n\n## Requests that find nothing\n\nA request for a resource belonging to another organization returns **404**, not 403. The API\ndoes not confirm that a resource it will not show you exists.",
    "x-status": "beta"
  },
  "servers": [
    {
      "url": "https://api.beket.ai/api/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "audits",
      "description": "An audit is one measurement target plus its configuration. Create one, configure it, then start a run. **Beta:** these shapes may change; see the changelog."
    },
    {
      "name": "configuration",
      "description": "What an audit measures against: competitors, languages and location, and the daily snapshot. **Beta:** these shapes may change; see the changelog."
    },
    {
      "name": "prompts",
      "description": "The questions an audit asks the AI surfaces. Generated from the brand profile, then reviewed and selected. **Beta:** these shapes may change; see the changelog."
    },
    {
      "name": "topics",
      "description": "The groups an audit's prompts are filed under. Reports can be sliced by topic. **Beta:** these shapes may change; see the changelog."
    },
    {
      "name": "first-party-terms",
      "description": "Searches people really ran — from your Google Ads search-terms report or a connected source — offered as prompts to track. **Beta:** these shapes may change; see the changelog."
    },
    {
      "name": "runs",
      "description": "A run measures the audit's prompts against the selected AI surfaces. Runs are asynchronous: start one, then poll. **Beta:** these shapes may change; see the changelog."
    },
    {
      "name": "results",
      "description": "What the audit measured: metrics, the report, and the snapshot history. **Beta:** these shapes may change; see the changelog."
    },
    {
      "name": "sources",
      "description": "The URLs AI answers cited, how they are classified, and which domains you watch. **Beta:** these shapes may change; see the changelog."
    },
    {
      "name": "facts",
      "description": "What the brand states about itself, to check AI answers against. **Beta:** these shapes may change; see the changelog."
    },
    {
      "name": "traffic",
      "description": "AI crawler requests to the brand's site and AI-referred visits from it, from the connected Cloudflare and GA4 accounts. **Beta:** these shapes may change; see the changelog."
    },
    {
      "name": "eeat",
      "description": "A page scored for Experience, Expertise, Authoritativeness and Trustworthiness. **Beta:** these shapes may change; see the changelog."
    },
    {
      "name": "actions",
      "description": "The work an audit recommends and the record of doing it. **Beta:** these shapes may change; see the changelog."
    },
    {
      "name": "content",
      "description": "Briefs and drafts for the pieces an audit's content roadmap recommends. **Beta:** these shapes may change; see the changelog."
    },
    {
      "name": "signals",
      "description": "Changes between runs worth attention. Open until the condition clears (resolved) or the organization's owner dismisses them in the dashboard. **Beta:** these shapes may change; see the changelog."
    },
    {
      "name": "zapier",
      "description": "Flat, polling-shaped reads for automation tools. The Beket Zapier app is built on these, and any integrator may use them. A per-key rate limit applies. **Beta** like the rest of the API, but the Zapier app depends on these shapes, so they change only by adding fields."
    },
    {
      "name": "meta",
      "description": "The machine-readable description of this API. **Beta:** the documented surface may change; see the changelog."
    }
  ],
  "paths": {
    "/audits": {
      "post": {
        "operationId": "createAudit",
        "summary": "Create an audit",
        "description": "Four ways to name the target, in one of four request shapes: an existing `entityId`, a `domain` (an entity is resolved or created for it), a `topic` for a market-mode audit, or an inline `profile` when you already know the brand details. The audit is created in a pending state — it does not begin measuring until you start a run.",
        "tags": [
          "audits"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The audit was created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "auditId": {
                          "type": "string"
                        },
                        "entityId": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "auditId",
                        "status"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "get": {
        "operationId": "listAudits",
        "summary": "List audits",
        "description": "Your organization's audits, newest first, cursor-paginated. Note that `nextCursor` sits BESIDE `data`, not inside it: pass it back as `?cursor=` to fetch the next page, and stop when it is null. Scores are null until the audit has produced a snapshot.",
        "tags": [
          "audits"
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque cursor from a previous response's `nextCursor`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "take",
            "in": "query",
            "required": false,
            "description": "Page size. Defaults to 50, capped at 100.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Only audits of this domain.",
            "schema": {
              "type": "string",
              "maxLength": 253
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of audits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "url": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "status": {
                            "type": "string"
                          },
                          "mode": {
                            "type": "string"
                          },
                          "brandName": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "faviconUrl": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "aeoScore": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "sovScore": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "snapshotEnabled": {
                            "type": "boolean"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "status"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "id": "clrecorderaudit0000000001",
                      "url": "example.com",
                      "status": "COMPLETED",
                      "mode": "brand",
                      "brandName": "Example Co",
                      "subjectPath": null,
                      "subjectLabel": "Example Co",
                      "faviconUrl": null,
                      "visibility": 62,
                      "sovScore": null,
                      "snapshotEnabled": true,
                      "createdAt": "2026-10-26T19:53:04.847Z",
                      "updatedAt": "2026-10-26T19:53:04.847Z",
                      "lastRunAt": "2026-10-25T19:53:04.851Z",
                      "cancelledAt": null,
                      "cancelsAt": null
                    }
                  ],
                  "nextCursor": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}": {
      "get": {
        "operationId": "getAudit",
        "summary": "Get an audit",
        "description": "The audit with its entity, profile, and angles. A request for an audit belonging to another organization returns 404, not 403 — the API does not confirm that it exists.",
        "tags": [
          "audits"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The audit.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "url": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "type": "string"
                        },
                        "error": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "entity": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "domain": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "name": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "category": {
                              "type": [
                                "string",
                                "null"
                              ]
                            }
                          },
                          "additionalProperties": true
                        },
                        "profile": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "additionalProperties": true,
                          "description": "The brand profile. Field set depends on how the audit was created and what discovery found."
                        },
                        "angles": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "synthesis": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "createdAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "required": [
                            "available",
                            "createdAt"
                          ],
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "id",
                        "status"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "clrecorderaudit0000000001",
                    "url": "example.com",
                    "subjectPath": null,
                    "status": "COMPLETED",
                    "error": null,
                    "createdAt": "2026-10-26T19:53:04.847Z",
                    "updatedAt": "2026-10-26T19:53:04.847Z",
                    "entity": {
                      "id": "clrecorderentity000000001",
                      "domain": "example.com",
                      "name": "Example Co",
                      "category": "SOFTWARE",
                      "faviconUrl": null,
                      "ogImageUrl": null
                    },
                    "profile": {
                      "brandName": "Example Co",
                      "category": null,
                      "description": "A fixture brand.",
                      "competitors": null,
                      "differentiators": null,
                      "icp": null
                    },
                    "angles": [
                      {
                        "angleId": "BRAND_DISCOVERY",
                        "status": "COMPLETED",
                        "error": null,
                        "updatedAt": "2026-10-26T19:53:04.854Z"
                      },
                      {
                        "angleId": "CUSTOM",
                        "status": "PENDING",
                        "error": null,
                        "updatedAt": "2026-10-26T19:53:04.914Z"
                      }
                    ],
                    "synthesis": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/prepare": {
      "post": {
        "operationId": "prepareAudit",
        "summary": "Prepare a newly created audit",
        "description": "**The required second step.** A new audit is created `PENDING`, which is not yet a state anything can be generated or run from: it has no brand profile, and prompts are generated from that profile. Preparing explores the target, infers the profile, and selects the angles, moving the audit `PENDING` → `PREPARING` → `AWAITING_CONFIG`.\n\n**This is asynchronous.** It answers **202** and returns immediately; the work happens on a queue. Poll `GET /audits/{auditId}` and wait for `status` to reach `AWAITING_CONFIG` before calling `POST /audits/{auditId}/prompts/generate` or `POST /audits/{auditId}/start` — both reject a `PENDING` or `PREPARING` audit with a 409.\n\n**This costs money** — it crawls the target and runs an LLM to infer the profile. Calling it twice while a prepare is already queued or running is a no-op rather than a second run of the work, but do not re-prepare an audit that is past `PENDING`: that redoes the exploration and clobbers configuration you have already set.",
        "tags": [
          "audits"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "202": {
            "description": "Preparation enqueued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "auditId": {
                          "type": "string"
                        },
                        "jobId": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "auditId"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is mid-run, so its inputs cannot be re-derived.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "authored"
      }
    },
    "/audits/{auditId}/config-options": {
      "get": {
        "operationId": "getAuditConfigOptions",
        "summary": "Get configuration options for an audit",
        "description": "What this audit may be configured with, given the organization's plan: selectable connectors, the connector ceiling, available languages and service areas, the angle list, and the inputs used to estimate a run's size. Read this before starting a run — the ceiling is plan-dependent, and a selection above it is clamped rather than rejected.",
        "tags": [
          "audits"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The configuration options.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "ready": {
                          "type": "boolean"
                        },
                        "status": {
                          "type": "string"
                        },
                        "availableConnectors": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "type": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "supportsModel": {
                                "type": "boolean"
                              },
                              "allowedModels": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "supportsLocation": {
                                "type": "boolean"
                              },
                              "supportsWebSearch": {
                                "type": "boolean"
                              },
                              "isCheapDefault": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "type",
                              "label"
                            ],
                            "additionalProperties": true
                          }
                        },
                        "connectorSelectability": {
                          "$ref": "#/components/schemas/ConnectorSelectability"
                        },
                        "maxConnectors": {
                          "type": "integer"
                        },
                        "languages": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "serviceAreas": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "angles": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "estimateInputs": {
                          "type": "object",
                          "properties": {
                            "angleCount": {
                              "type": "integer"
                            },
                            "queriesPerAngle": {
                              "type": "integer"
                            },
                            "maxExecutions": {
                              "type": "integer"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "ready",
                        "status"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "ready": false,
                    "status": "COMPLETED",
                    "availableConnectors": [
                      {
                        "type": "CHATGPT_APP",
                        "label": "ChatGPT",
                        "supportsModel": false,
                        "allowedModels": [],
                        "supportsLocation": true,
                        "supportsWebSearch": true,
                        "dotColor": "#000000",
                        "isCheapDefault": false
                      },
                      {
                        "type": "GOOGLE_AI_OVERVIEW",
                        "label": "AI Overview",
                        "supportsModel": false,
                        "allowedModels": [],
                        "supportsLocation": true,
                        "supportsWebSearch": true,
                        "dotColor": "#f59e0b",
                        "isCheapDefault": false
                      }
                    ],
                    "connectorSelectability": [
                      {
                        "type": "CHATGPT_APP",
                        "label": "ChatGPT",
                        "locked": false,
                        "preselected": true,
                        "reason": "ok"
                      },
                      {
                        "type": "GOOGLE_AI_OVERVIEW",
                        "label": "AI Overview",
                        "locked": false,
                        "preselected": true,
                        "reason": "ok"
                      }
                    ],
                    "maxConnectors": 5,
                    "languages": [
                      "EN"
                    ],
                    "serviceAreas": [],
                    "angles": [
                      {
                        "angleId": "BRAND_DISCOVERY",
                        "label": "Brand Discovery",
                        "querySubjects": [
                          "CATEGORY"
                        ]
                      },
                      {
                        "angleId": "CUSTOM",
                        "label": "Custom",
                        "querySubjects": []
                      }
                    ],
                    "estimateInputs": {
                      "angleCount": 2,
                      "queriesPerAngle": 4,
                      "maxExecutions": 3500
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/profile": {
      "get": {
        "operationId": "getAuditProfile",
        "summary": "Get an audit's brand profile",
        "description": "The profile the prompts are generated from. Returns an empty profile object rather than 404 when none has been extracted yet, so a client can render the form either way.",
        "tags": [
          "audits"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The profile.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "profile": {
                          "type": "object",
                          "additionalProperties": true,
                          "description": "Brand profile fields — name, category, description, products, competitors."
                        }
                      },
                      "required": [
                        "profile"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "profile": {
                      "brandName": "Example Co",
                      "brandAliases": [],
                      "primaryProduct": "Widgets",
                      "offer": "Widgets that work",
                      "description": "A fixture brand.",
                      "icp": [],
                      "differentiators": [],
                      "painPoints": [],
                      "vertical": null,
                      "categoryLabel": null,
                      "segment": null,
                      "marketScope": null,
                      "city": null,
                      "serviceRadius": null,
                      "anchors": null,
                      "neutralDescription": null,
                      "painPrompts": [],
                      "verifiedClaims": []
                    },
                    "claimsSeeded": true
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "patch": {
        "operationId": "updateAuditProfile",
        "summary": "Replace an audit's brand profile",
        "description": "Overwrites the editable profile fields — send the whole object, not a partial patch, because absent nullable fields are written as null. Free-text list fields are trimmed, de-duplicated, and blank entries dropped rather than rejected.\n\n**One rule the schema below cannot express:** `categoryLabel` must say what the brand does, not how it ranks — \"commercial cleaning\" is accepted, \"best\" is rejected with a 400. (It is enforced by a zod refinement, and refinements have no JSON Schema equivalent.)\n\nThe audit must have an entity; a market-mode audit with no owned domain returns 400.",
        "tags": [
          "audits"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditProfileUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The saved profile.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "profile": {
                          "type": "object",
                          "additionalProperties": true,
                          "description": "The profile as persisted."
                        }
                      },
                      "required": [
                        "profile"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "profile": {
                      "brandName": "Example Co",
                      "brandAliases": [],
                      "primaryProduct": "Widgets",
                      "offer": "Widgets that work",
                      "description": "A fixture brand.",
                      "icp": [
                        "Operations teams"
                      ],
                      "differentiators": [],
                      "painPoints": [],
                      "vertical": null,
                      "categoryLabel": "widget software",
                      "segment": null,
                      "marketScope": null,
                      "city": null,
                      "serviceRadius": null,
                      "anchors": null,
                      "neutralDescription": null,
                      "painPrompts": [],
                      "verifiedClaims": []
                    },
                    "claimsSeeded": true
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/connectors": {
      "get": {
        "operationId": "getAuditConnectors",
        "summary": "Get an audit's selected connectors",
        "description": "Which AI surfaces this audit queries, plus the plan's per-connector selectability and ceiling. `connectorTypes` is the current selection; `selectability` explains why a connector is or is not available to this organization.",
        "tags": [
          "audits"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The connector selection.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/ConnectorSelection"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "connectorTypes": [],
                    "selectability": [
                      {
                        "type": "CHATGPT_APP",
                        "label": "ChatGPT",
                        "locked": false,
                        "preselected": true,
                        "reason": "ok"
                      },
                      {
                        "type": "GOOGLE_AI_OVERVIEW",
                        "label": "AI Overview",
                        "locked": false,
                        "preselected": true,
                        "reason": "ok"
                      }
                    ],
                    "maxConnectors": 5
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "patch": {
        "operationId": "updateAuditConnectors",
        "summary": "Replace an audit's selected connectors",
        "description": "Sets which AI surfaces this audit queries. The selection is **clamped to the plan's ceiling rather than rejected** — read `maxConnectors` back from the response to see what was actually kept. Returns 409 while the audit is in a state where its configuration is not editable (mid-run, for instance), so check the audit's status first.",
        "tags": [
          "audits"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditConnectorsUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The saved selection.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/ConnectorSelection"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "connectorTypes": [
                      "CHATGPT_APP"
                    ],
                    "selectability": [
                      {
                        "type": "CHATGPT_APP",
                        "label": "ChatGPT",
                        "locked": false,
                        "preselected": true,
                        "reason": "ok"
                      },
                      {
                        "type": "GOOGLE_AI_OVERVIEW",
                        "label": "AI Overview",
                        "locked": false,
                        "preselected": true,
                        "reason": "ok"
                      }
                    ],
                    "maxConnectors": 5
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit's configuration is not editable in its current status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/competitors": {
      "get": {
        "operationId": "getAuditCompetitors",
        "summary": "List an audit's competitors",
        "description": "The competitors this audit compares the brand against — the list a person curated. Names a run discovered on its own are not in it.",
        "tags": [
          "configuration"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The competitors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/AuditCompetitors"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "competitors": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "patch": {
        "operationId": "updateAuditCompetitors",
        "summary": "Replace an audit's competitors",
        "description": "Replaces the curated list. Entries are trimmed, their domains normalized, and duplicates by name collapsed, so the response may hold fewer than you sent. Mention metrics are recomputed in the background. Market audits have no competitors to edit.",
        "tags": [
          "configuration"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditCompetitorsUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The competitors as stored.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/AuditCompetitors"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "competitors": [
                      {
                        "name": "Rival",
                        "domain": "rival.com",
                        "sizeTier": "unknown"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/targeting": {
      "get": {
        "operationId": "getAuditTargeting",
        "summary": "Read an audit's targeting",
        "description": "The languages prompts are written in and the location answers are requested from.",
        "tags": [
          "configuration"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The targeting, with suggestions.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/AuditTargeting"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "languages": [],
                    "locations": [],
                    "languageSuggestions": [
                      "EN"
                    ],
                    "locationSuggestions": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "patch": {
        "operationId": "updateAuditTargeting",
        "summary": "Set an audit's targeting",
        "description": "Replaces the languages and location. Languages may be sent as names (`English`) or codes; they are stored and returned as ISO 639-1 codes. Applies to prompts generated and runs started after the change.",
        "tags": [
          "configuration"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditTargetingUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The targeting as stored.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/AuditTargeting"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "languages": [
                      "EN"
                    ],
                    "locations": [
                      "United States"
                    ],
                    "languageSuggestions": [
                      "EN"
                    ],
                    "locationSuggestions": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is running. Targeting can be changed only while it is AWAITING_CONFIG, AWAITING_PROMPTS, COMPLETED or FAILED.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/schedule": {
      "patch": {
        "operationId": "updateAuditSnapshotSchedule",
        "summary": "Turn the daily snapshot on or off",
        "description": "Toggles the daily snapshot and sets the time zone whose night it runs in. The zone applies whether or not a schedule exists yet; the toggle needs one, which an audit gets after its first full run. The schedule fields are absent until then.",
        "tags": [
          "configuration"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditSchedulePatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The schedule after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "auditId": {
                          "type": "string"
                        },
                        "intervalHours": {
                          "type": "integer"
                        },
                        "snapshotLabelPrefix": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "options": {
                          "type": "object",
                          "additionalProperties": true,
                          "description": "The run options each scheduled run uses."
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "nextRunAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "runCount": {
                          "type": "integer"
                        },
                        "lastError": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "snapshotEnabled": {
                          "type": "boolean",
                          "description": "Whether the daily snapshot runs."
                        },
                        "snapshotTimeZone": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "This audit's own zone override; `null` when it has none."
                        },
                        "resolvedSnapshotTimeZone": {
                          "type": "string",
                          "description": "The zone that actually applies — the override, or the organization's."
                        }
                      },
                      "required": [
                        "snapshotTimeZone",
                        "resolvedSnapshotTimeZone"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "snapshotTimeZone": "America/New_York",
                    "resolvedSnapshotTimeZone": "America/New_York"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/profile/gbp-suggestion": {
      "get": {
        "operationId": "getAuditGbpSuggestion",
        "summary": "Suggest the brand's Google Business Profile",
        "description": "A best guess at the brand's own Google Business Profile, looked up on Google Maps from its name and city, for you to confirm. `null` when nothing matched, when the profile already names one, or when the audit has no brand profile — never an error.",
        "tags": [
          "configuration"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The suggestion.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "suggestion": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "placeId": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            },
                            "formattedAddress": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "phone": {
                              "type": [
                                "string",
                                "null"
                              ]
                            }
                          },
                          "required": [
                            "placeId",
                            "name"
                          ],
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "suggestion"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "suggestion": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/angles": {
      "get": {
        "operationId": "listAngles",
        "summary": "List the prompt angles",
        "description": "The active angles — the categories prompts are filed under — in display order.",
        "tags": [
          "configuration"
        ],
        "responses": {
          "200": {
            "description": "The angles.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "angles": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "group": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "id",
                              "label"
                            ],
                            "additionalProperties": true
                          }
                        }
                      },
                      "required": [
                        "angles"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "angles": [
                      {
                        "id": "angle-winnable-queries-int-test",
                        "label": "winnable int test",
                        "group": "AWARENESS_DISCOVERY"
                      },
                      {
                        "id": "RETENTION_EXPANSION",
                        "label": "Retention / Expansion",
                        "group": "EXPANSION"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/changes": {
      "get": {
        "operationId": "listAuditChanges",
        "summary": "List configuration changes",
        "description": "Who changed the audit's profile, competitors, prompts, topics, facts, engines or targeting, and what changed, newest first. At most 200.",
        "tags": [
          "configuration"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The changes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "changes": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "entityType": {
                                "type": "string",
                                "enum": [
                                  "profile",
                                  "competitor",
                                  "query",
                                  "connectors",
                                  "targeting",
                                  "topic",
                                  "brandFact"
                                ]
                              },
                              "action": {
                                "type": "string",
                                "enum": [
                                  "create",
                                  "update",
                                  "delete"
                                ]
                              },
                              "field": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The field edited; `null` for a whole-row create or delete."
                              },
                              "oldValue": {
                                "description": "The value before, in the field's own JSON shape."
                              },
                              "newValue": {
                                "description": "The value after, in the field's own JSON shape."
                              },
                              "actorEmail": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "actingAsOrgId": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Set when Beket support made the change on your behalf."
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              }
                            },
                            "required": [
                              "id",
                              "entityType",
                              "action",
                              "field",
                              "oldValue",
                              "newValue",
                              "actorEmail",
                              "actingAsOrgId",
                              "createdAt"
                            ],
                            "additionalProperties": true
                          }
                        }
                      },
                      "required": [
                        "changes"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "changes": [
                      {
                        "id": "fca6152b-ff37-45b4-9b30-84f1e4ac9539",
                        "entityType": "brandFact",
                        "action": "update",
                        "field": "claim",
                        "oldValue": {
                          "id": "0cbd0f1b-9921-4eb3-ac83-38789de11596",
                          "state": "draft",
                          "value": "Open 24 hours"
                        },
                        "newValue": {
                          "id": "0cbd0f1b-9921-4eb3-ac83-38789de11596",
                          "state": "rejected",
                          "value": "Open 24 hours"
                        },
                        "actorEmail": "redacted@example.com",
                        "actingAsOrgId": null,
                        "createdAt": "2026-10-26T19:53:05.436Z"
                      },
                      {
                        "id": "ff168e1d-ec64-4cf7-958b-f36c9a8e6e43",
                        "entityType": "brandFact",
                        "action": "update",
                        "field": "claim",
                        "oldValue": null,
                        "newValue": {
                          "id": "c47baa43-276c-45d4-93d5-09a3e26a7580",
                          "state": "confirmed",
                          "value": "Family owned since 1998"
                        },
                        "actorEmail": "redacted@example.com",
                        "actingAsOrgId": null,
                        "createdAt": "2026-10-26T19:53:05.424Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/entities/review": {
      "get": {
        "operationId": "listAuditEntityReview",
        "summary": "List names to review",
        "description": "The names AI answers mention that are neither the brand nor a curated competitor, most mentioned first, at most 100 per page. Each carries the competitors it may be another spelling of.",
        "tags": [
          "configuration"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Only names containing this text.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "`pending` (the default): names not yet given a type; `overridden`: names given one; `all`: both.",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "overridden",
                "all"
              ]
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Names to skip. Default 0.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Names per page, 1–100. Default 100.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "entities": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "nameKey": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string",
                                "description": "The most common spelling."
                              },
                              "mentions": {
                                "type": "integer"
                              },
                              "answers": {
                                "type": "integer"
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "brand",
                                  "competitor",
                                  "place",
                                  "ai_platform",
                                  "person",
                                  "publisher",
                                  "generic"
                                ]
                              },
                              "override": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "enum": [
                                  "place",
                                  "ai_platform",
                                  "person",
                                  "publisher",
                                  "generic",
                                  null
                                ]
                              },
                              "suggestions": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "name": {
                                      "type": "string"
                                    },
                                    "reason": {
                                      "type": "string",
                                      "enum": [
                                        "same_name",
                                        "contains_name"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "name",
                                    "reason"
                                  ],
                                  "additionalProperties": true
                                }
                              }
                            },
                            "required": [
                              "nameKey",
                              "name",
                              "mentions",
                              "answers",
                              "kind",
                              "override",
                              "suggestions"
                            ],
                            "additionalProperties": true
                          }
                        },
                        "total": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "entities",
                        "total",
                        "offset",
                        "limit"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "entities": [
                      {
                        "kind": "generic",
                        "name": "Acme Labs",
                        "answers": 1,
                        "nameKey": "n:acmelabs",
                        "mentions": 2,
                        "override": null,
                        "suggestions": []
                      },
                      {
                        "kind": "generic",
                        "name": "WidgetHub",
                        "answers": 1,
                        "nameKey": "n:widgethub",
                        "mentions": 2,
                        "override": null,
                        "suggestions": []
                      }
                    ],
                    "total": 2,
                    "offset": 0,
                    "limit": 100
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/entities/type": {
      "put": {
        "operationId": "setAuditEntityType",
        "summary": "Set what a name is",
        "description": "Marks a name as something other than a competitor, so the report stops counting it as one. `kind: null` clears the override.",
        "tags": [
          "configuration"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EntityTypeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/EntityEditResult"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "nameKey": "n:widgethub",
                    "outcome": "applied"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The edit was refused (`error.details.code`: `is_brand`, `tracked`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/entities/merge": {
      "put": {
        "operationId": "mergeAuditEntity",
        "summary": "File a name under a competitor",
        "description": "Records the name as another spelling of the competitor `into`, so its mentions count for that competitor. `into: null` unmerges it.",
        "tags": [
          "configuration"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EntityMergeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/EntityEditResult"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "nameKey": "n:acmelabs",
                    "outcome": "applied"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The edit was refused (`error.details.code`: `is_brand`, `excluded_target`, `tracked`, `alias_cap`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/entities/import": {
      "post": {
        "operationId": "importAuditEntityEdits",
        "summary": "Import name edits from CSV",
        "description": "Applies many edits from a CSV with the header `name,type,merge_into`, at most 500 rows and 200,000 characters. All or none: if any row is refused, nothing is applied and the **422** lists the refused rows in `error.details.rows`.",
        "tags": [
          "configuration"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EntityImportRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Every row, applied.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "rows": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "line": {
                                "type": "integer"
                              },
                              "name": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "applied",
                                  "unchanged"
                                ]
                              }
                            },
                            "required": [
                              "line",
                              "name",
                              "status"
                            ],
                            "additionalProperties": true
                          }
                        }
                      },
                      "required": [
                        "rows"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "rows": [
                      {
                        "line": 2,
                        "name": "Gadgetly",
                        "status": "applied"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "Some rows were refused and nothing was applied. Each entry in `error.details.rows` has `line`, `message`, and — for a refused edit — `name` and `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/prompts": {
      "get": {
        "operationId": "getAuditPrompts",
        "summary": "List an audit's prompts",
        "description": "The prompt set with its selection state. `ready` is true when the audit is waiting for prompt review, and `maxQueries` is the plan's ceiling on how many may be selected — selecting more than that is rejected when the run starts, not here.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The prompt set.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/PromptSet"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "ready": false,
                    "status": "COMPLETED",
                    "prompts": [
                      {
                        "id": "0f4d5c46-b98e-4854-af39-2f6c7a32c038",
                        "text": "best widget software for small teams",
                        "selected": true,
                        "angleId": "CUSTOM",
                        "language": null,
                        "promptType": "UNBRANDED",
                        "topicId": null,
                        "region": null,
                        "querySubject": "OFFERING",
                        "funnelStage": null,
                        "angleLabel": "Custom",
                        "isCustom": true,
                        "branded": false
                      },
                      {
                        "id": "a3985077-683f-4df2-9b51-6474baab91e2",
                        "text": "how do I choose a widget vendor",
                        "selected": true,
                        "angleId": "CUSTOM",
                        "language": null,
                        "promptType": "UNBRANDED",
                        "topicId": null,
                        "region": null,
                        "querySubject": "OFFERING",
                        "funnelStage": null,
                        "angleLabel": "Custom",
                        "isCustom": true,
                        "branded": false
                      }
                    ],
                    "maxQueries": 25
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "post": {
        "operationId": "addAuditPrompt",
        "summary": "Add a prompt",
        "description": "Adds one prompt you wrote (3–500 characters). It is selected when the plan has room and lands unselected otherwise — an add is never refused for capacity. It starts under the `CUSTOM` angle and is moved to a better-fitting angle in the background, so a later read may show a different `angleId`.\n\n`selectedIds` is optional: send it to replace the selection of existing prompts in the same transaction as the add — the way to make room on a plan whose minimum and maximum selection are equal, where a separate deselect would be refused. Omit it to leave the selection alone.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromptAddRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The added prompt.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "prompt": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "text": {
                              "type": "string"
                            },
                            "selected": {
                              "type": "boolean"
                            },
                            "angleId": {
                              "type": "string"
                            },
                            "angleLabel": {
                              "type": "string"
                            },
                            "querySubject": {
                              "type": "string"
                            },
                            "funnelStage": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "isCustom": {
                              "type": "boolean"
                            },
                            "branded": {
                              "type": "boolean",
                              "description": "Absent when the phrasing could not be classified."
                            },
                            "language": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "id",
                            "text",
                            "selected",
                            "angleId",
                            "isCustom"
                          ],
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "prompt"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "prompt": {
                      "id": "c4fdd333-0f2f-49d4-9ccf-5740eae5d56b",
                      "text": "which widget tools integrate with spreadsheets",
                      "querySubject": "OFFERING",
                      "funnelStage": null,
                      "selected": true,
                      "angleId": "CUSTOM",
                      "angleLabel": "Custom",
                      "isCustom": true,
                      "branded": false,
                      "language": "EN"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is running. Prompts can be edited only while it is AWAITING_CONFIG, AWAITING_PROMPTS, COMPLETED or FAILED.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/prompts/bulk": {
      "post": {
        "operationId": "addAuditPromptsBulk",
        "summary": "Add up to 100 prompts",
        "description": "Adds up to 100 prompts in one request, one per entry in `texts`. Each line is cleaned the way the dashboard's paste box cleans it (list markers, numbering and surrounding quotes are stripped). If any line is out of bounds the whole request is a 400 naming every bad line, and nothing is added. Duplicates — within the list or of a prompt already on the audit — are skipped and counted in `skippedDuplicates`, so sending the same list twice is safe.\n\nNew prompts are selected while the plan has room. `selectedIds` is optional: send it to replace the selection of existing prompts in the same transaction as the add — the way to make room on a plan whose minimum and maximum selection are equal, where a separate deselect would be refused. Omit it to leave the selection alone. `selectedIds: []` deselects every existing prompt.\n\nSend `returnPrompts: false` to receive only the counts: the full list can run to tens of kilobytes, and an automation rarely needs it.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromptBulkAddRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "What was added.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "prompts": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Prompt"
                          }
                        },
                        "maxQueries": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "added": {
                          "type": "integer"
                        },
                        "selected": {
                          "type": "integer",
                          "description": "How many of the added prompts were selected."
                        },
                        "skippedDuplicates": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "maxQueries",
                        "added",
                        "selected",
                        "skippedDuplicates"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "maxQueries": 25,
                    "added": 2,
                    "selected": 2,
                    "skippedDuplicates": 0
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is running. Prompts can be edited only while it is AWAITING_CONFIG, AWAITING_PROMPTS, COMPLETED or FAILED.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/prompts/selection": {
      "patch": {
        "operationId": "updateAuditPromptSelection",
        "summary": "Set which prompts are selected",
        "description": "Replaces the selection: the prompts named in `selectedIds` are selected and every other prompt is not. Ids that are not live prompts of this audit are ignored. On a paid plan the selection has a floor, so a run stays meaningful; going under it is a 400 that names the minimum.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromptSelectionUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The prompt list after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "prompts": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Prompt"
                          }
                        },
                        "maxQueries": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "prompts",
                        "maxQueries"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "prompts": [
                      {
                        "id": "0f4d5c46-b98e-4854-af39-2f6c7a32c038",
                        "text": "best widget software for small teams",
                        "selected": true,
                        "angleId": "CUSTOM",
                        "language": null,
                        "promptType": "UNBRANDED",
                        "topicId": null,
                        "region": null,
                        "querySubject": "OFFERING",
                        "funnelStage": null,
                        "angleLabel": "Custom",
                        "isCustom": true,
                        "branded": false
                      },
                      {
                        "id": "a3985077-683f-4df2-9b51-6474baab91e2",
                        "text": "how do I choose a widget vendor",
                        "selected": true,
                        "angleId": "CUSTOM",
                        "language": null,
                        "promptType": "UNBRANDED",
                        "topicId": null,
                        "region": null,
                        "querySubject": "OFFERING",
                        "funnelStage": null,
                        "angleLabel": "Custom",
                        "isCustom": true,
                        "branded": false
                      }
                    ],
                    "maxQueries": 25
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is running, or the selection is over the plan's prompt capacity (the error says how many prompts are left).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/prompts/{promptId}": {
      "delete": {
        "operationId": "deleteAuditPrompt",
        "summary": "Remove a prompt",
        "description": "Takes the prompt out of the set. A prompt that has already been answered is archived rather than deleted, so its history stays in past snapshots; `removed` says which happened. Either way it no longer appears in the list.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "$ref": "#/components/parameters/promptId"
          }
        ],
        "responses": {
          "200": {
            "description": "The prompt list after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/PromptRemoval"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "prompts": [
                      {
                        "id": "0f4d5c46-b98e-4854-af39-2f6c7a32c038",
                        "text": "best widget software for small teams",
                        "selected": true,
                        "angleId": "CUSTOM",
                        "language": null,
                        "promptType": "UNBRANDED",
                        "topicId": null,
                        "region": null,
                        "querySubject": "OFFERING",
                        "funnelStage": null,
                        "angleLabel": "Custom",
                        "isCustom": true,
                        "branded": false
                      },
                      {
                        "id": "a3985077-683f-4df2-9b51-6474baab91e2",
                        "text": "how do I choose a widget vendor",
                        "selected": true,
                        "angleId": "CUSTOM",
                        "language": null,
                        "promptType": "UNBRANDED",
                        "topicId": null,
                        "region": null,
                        "querySubject": "OFFERING",
                        "funnelStage": null,
                        "angleLabel": "Custom",
                        "isCustom": true,
                        "branded": false
                      }
                    ],
                    "maxQueries": 25,
                    "removed": "deleted"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is running. Prompts can be edited only while it is AWAITING_CONFIG, AWAITING_PROMPTS, COMPLETED or FAILED.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/prompts/generate": {
      "post": {
        "operationId": "generateAuditPrompts",
        "summary": "Generate an audit's prompt set",
        "description": "Generates the prompts for this audit and returns the resulting set, leaving the audit awaiting prompt review. **This call costs money** — it runs an LLM generation — so treat it as a one-time step per audit rather than something to retry casually.\n\nBoth body fields are optional. Sending a non-empty `topicIds` selects the deterministic template path; omitting it generates over the audit's selected angles. `languages` overrides the audit's stored targeting languages for this generation only.\n\n**Requires `status` to be `AWAITING_CONFIG` or `AWAITING_PROMPTS`**, and answers 409 otherwise. A newly created audit is `PENDING`: call `POST /audits/{auditId}/prepare` first and wait for it to reach `AWAITING_CONFIG`.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromptGenerateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The generated prompt set.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/PromptSet"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is not AWAITING_CONFIG or AWAITING_PROMPTS — a newly created audit is PENDING until it has been prepared.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "authored"
      }
    },
    "/audits/{auditId}/prompts/preview": {
      "post": {
        "operationId": "previewAuditPrompts",
        "summary": "Preview prompts from an unsaved profile",
        "description": "Renders the prompts the template path would generate from the profile, competitors and topics in the body — not the audit's stored ones — so an editor can show them before saving. Deterministic and free: no LLM runs and nothing is written. Every body field is optional.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromptPreviewRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The prompts that would be generated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "prompts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "text": {
                                "type": "string"
                              },
                              "branded": {
                                "type": "boolean"
                              },
                              "language": {
                                "type": "string"
                              },
                              "topicId": {
                                "type": "string",
                                "description": "The catalog topic the prompt came from."
                              },
                              "funnelStage": {
                                "type": "string",
                                "enum": [
                                  "awareness",
                                  "consideration",
                                  "decision"
                                ]
                              }
                            },
                            "required": [
                              "text",
                              "branded",
                              "language",
                              "topicId",
                              "funnelStage"
                            ],
                            "additionalProperties": true
                          }
                        }
                      },
                      "required": [
                        "prompts"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "prompts": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/prompts/generate-more": {
      "post": {
        "operationId": "generateMoreAuditPrompts",
        "summary": "Generate more prompts",
        "description": "Tops the set back up: each selected angle short of its share of the plan's prompt limit gets new LLM-generated prompts, skipping texts the audit already has. Existing prompts are kept. **This call costs money** — it runs an LLM generation.\n\n**Requires `status` to be `AWAITING_PROMPTS`** (after `POST /audits/{auditId}/prompts/generate`) and an organization plan; answers 409 otherwise, and when every angle is already at its limit. A 400 means the audit has no brand profile or no selected angles to generate from.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The prompt set with the new prompts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/PromptSet"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is not AWAITING_PROMPTS, has no plan to size the set against, or every angle is already at its prompt limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "authored"
      }
    },
    "/audits/{auditId}/prompts/manage": {
      "get": {
        "operationId": "listAuditPromptsPaged",
        "summary": "Page through an audit's prompts",
        "description": "One page of prompts, filtered and sorted, with the plan's capacity. Unlike `GET /audits/{auditId}/prompts`, archived prompts can be listed too. Pass `nextCursor` back as `cursor` for the next page; it is `null` on the last one.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque cursor from a previous page's `nextCursor`.",
            "schema": {
              "type": "string",
              "maxLength": 512
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size.",
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Active prompts, or the archived ones.",
            "schema": {
              "default": "active",
              "type": "string",
              "enum": [
                "active",
                "archived"
              ]
            }
          },
          {
            "name": "topicId",
            "in": "query",
            "required": false,
            "description": "Only prompts in this topic; `none` lists prompts in no topic.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "promptType",
            "in": "query",
            "required": false,
            "description": "Only prompts of this type.",
            "schema": {
              "type": "string",
              "enum": [
                "UNBRANDED",
                "BRANDED",
                "RECALL"
              ]
            }
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "description": "Only prompts in this language, as a code or name (`en`, `English`); `none` lists prompts whose language is unknown.",
            "schema": {
              "type": "string",
              "maxLength": 32
            }
          },
          {
            "name": "selected",
            "in": "query",
            "required": false,
            "description": "Only prompts that are (`true`) or are not (`false`) selected to run.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Only prompts whose text contains this.",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "prompts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "text": {
                                "type": "string"
                              },
                              "promptType": {
                                "type": "string",
                                "enum": [
                                  "UNBRANDED",
                                  "BRANDED",
                                  "RECALL"
                                ]
                              },
                              "topicId": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "angleId": {
                                "type": "string"
                              },
                              "language": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "region": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "active",
                                  "archived"
                                ]
                              },
                              "selected": {
                                "type": "boolean"
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "createdBy": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Who added it; `null` for a generated prompt."
                              },
                              "mined": {
                                "type": "boolean",
                                "description": "Found in search results rather than generated or written."
                              }
                            },
                            "required": [
                              "id",
                              "text",
                              "promptType",
                              "status",
                              "selected",
                              "createdAt",
                              "mined"
                            ],
                            "additionalProperties": true
                          }
                        },
                        "nextCursor": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "capacity": {
                          "$ref": "#/components/schemas/PromptCapacity"
                        }
                      },
                      "required": [
                        "prompts",
                        "nextCursor",
                        "capacity"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "prompts": [
                      {
                        "id": "a3985077-683f-4df2-9b51-6474baab91e2",
                        "text": "how do I choose a widget vendor",
                        "selected": true,
                        "angleId": "CUSTOM",
                        "language": null,
                        "promptType": "UNBRANDED",
                        "topicId": null,
                        "region": null,
                        "status": "active",
                        "createdAt": "2026-10-26T19:53:04.923Z",
                        "createdBy": null,
                        "mined": false
                      },
                      {
                        "id": "0f4d5c46-b98e-4854-af39-2f6c7a32c038",
                        "text": "best widget software for small teams",
                        "selected": true,
                        "angleId": "CUSTOM",
                        "language": null,
                        "promptType": "UNBRANDED",
                        "topicId": null,
                        "region": null,
                        "status": "active",
                        "createdAt": "2026-10-26T19:53:04.923Z",
                        "createdBy": null,
                        "mined": false
                      }
                    ],
                    "nextCursor": null,
                    "capacity": {
                      "used": 2,
                      "cap": 25,
                      "left": 23
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/prompts/summary": {
      "get": {
        "operationId": "getAuditPromptSummary",
        "summary": "Count an audit's prompts",
        "description": "Counts by state, type and topic — the cheap read for a status line.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The counts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "capacity": {
                          "$ref": "#/components/schemas/PromptCapacity"
                        },
                        "active": {
                          "type": "integer"
                        },
                        "archived": {
                          "type": "integer"
                        },
                        "byType": {
                          "type": "object",
                          "properties": {
                            "UNBRANDED": {
                              "type": "integer"
                            },
                            "BRANDED": {
                              "type": "integer"
                            },
                            "RECALL": {
                              "type": "integer"
                            }
                          },
                          "additionalProperties": true,
                          "description": "Active prompts by type."
                        },
                        "topics": {
                          "type": "integer"
                        },
                        "unassigned": {
                          "type": "integer",
                          "description": "Active prompts filed under no topic."
                        },
                        "auditStatus": {
                          "type": "string",
                          "description": "Prompt writes are refused with 409 while the audit runs."
                        }
                      },
                      "required": [
                        "capacity",
                        "active",
                        "archived",
                        "byType",
                        "topics",
                        "unassigned",
                        "auditStatus"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "capacity": {
                      "used": 2,
                      "cap": 25,
                      "left": 23
                    },
                    "active": 3,
                    "archived": 0,
                    "byType": {
                      "UNBRANDED": 3,
                      "BRANDED": 0,
                      "RECALL": 0
                    },
                    "topics": 0,
                    "unassigned": 3,
                    "auditStatus": "COMPLETED"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/prompts/actions": {
      "post": {
        "operationId": "applyAuditPromptAction",
        "summary": "Act on many prompts at once",
        "description": "Applies one action — `select`, `deselect`, `remove`, `restore` — to up to 500 prompts, and reports what happened to each. `remove` archives a prompt that has been answered and deletes one that has not; `removed` counts both.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromptActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Each prompt's outcome.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "action": {
                          "type": "string",
                          "enum": [
                            "select",
                            "deselect",
                            "remove",
                            "restore"
                          ]
                        },
                        "results": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "outcome": {
                                "type": "string",
                                "enum": [
                                  "changed",
                                  "unchanged",
                                  "not_found",
                                  "duplicate",
                                  "archived"
                                ]
                              }
                            },
                            "required": [
                              "id",
                              "outcome"
                            ],
                            "additionalProperties": true
                          }
                        },
                        "removed": {
                          "type": "object",
                          "properties": {
                            "archived": {
                              "type": "integer"
                            },
                            "deleted": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "archived",
                            "deleted"
                          ],
                          "additionalProperties": true
                        },
                        "capacity": {
                          "$ref": "#/components/schemas/PromptCapacity"
                        }
                      },
                      "required": [
                        "action",
                        "results",
                        "capacity"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "action": "select",
                    "results": [
                      {
                        "id": "0f4d5c46-b98e-4854-af39-2f6c7a32c038",
                        "outcome": "unchanged"
                      },
                      {
                        "id": "a3985077-683f-4df2-9b51-6474baab91e2",
                        "outcome": "unchanged"
                      }
                    ],
                    "capacity": {
                      "used": 3,
                      "cap": 25,
                      "left": 22
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is running — prompts are locked until it finishes, or the change would cross the plan's capacity: `error.details.code` is `over_capacity` (with `left`, `requested`, `cap`) or `below_floor` (with `floor`, `selected`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/prompts/import": {
      "post": {
        "operationId": "importAuditPrompts",
        "summary": "Import prompts from a CSV",
        "description": "Adds prompts from a CSV file sent as text (at most 1000 rows and 5 MB). A `prompt` column is required and a `topic` column files each row, creating up to 50 new topics; other columns are reported in `ignoredColumns`. A file from the export re-imports as-is.\n\nSend `dryRun: true` first: it answers 200 with the same per-row report and writes nothing. A real import answers 201. Rows over the plan's capacity are added unselected (`over_capacity`), never refused.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromptImportRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The dry-run report. Nothing was written.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/PromptImportReport"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "dryRun": true,
                    "counts": {
                      "added": 1,
                      "restored": 0,
                      "over_capacity": 0,
                      "duplicate": 0,
                      "invalid": 0
                    },
                    "topics": {
                      "matched": 0,
                      "created": 1
                    },
                    "ignoredColumns": [],
                    "maxQueries": 25,
                    "rows": [
                      {
                        "row": 1,
                        "outcome": "added"
                      }
                    ]
                  }
                }
              }
            }
          },
          "201": {
            "description": "The import report.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/PromptImportReport"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is running. Prompts can be edited only while it is AWAITING_CONFIG, AWAITING_PROMPTS, COMPLETED or FAILED.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "The file could not be read as a prompt CSV, or (not on a dry run) no row holds a prompt to import.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/prompts/export.csv": {
      "get": {
        "operationId": "exportAuditPromptsCsv",
        "summary": "Export prompts as CSV",
        "description": "Every prompt, active and archived, as a CSV download whose headers the import accepts. Past 5000 rows the file ends with a `# truncated` line; page the rest with `GET /audits/{auditId}/prompts/manage`.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The prompts as a CSV file, UTF-8 with a byte-order mark.",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "none"
      }
    },
    "/audits/{auditId}/prompts/{promptId}/dismiss": {
      "post": {
        "operationId": "dismissAuditMinedPrompt",
        "summary": "Dismiss a mined prompt",
        "description": "Removes a prompt found in search results (`mined: true`) and remembers the dismissal, so the next run does not find it again. Other prompts are removed with `DELETE /audits/{auditId}/prompts/{promptId}`.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "$ref": "#/components/parameters/promptId"
          }
        ],
        "responses": {
          "200": {
            "description": "The prompt list after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/PromptRemoval"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is running. Prompts can be edited only while it is AWAITING_CONFIG, AWAITING_PROMPTS, COMPLETED or FAILED.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/prompts/{promptId}/type": {
      "patch": {
        "operationId": "updateAuditPromptType",
        "summary": "Set a prompt's type",
        "description": "Overrides the classifier's branded/unbranded call. `promptTypeSource` becomes `user`, so a later reclassification leaves it alone. `RECALL` is fixed: no prompt moves into or out of it.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "$ref": "#/components/parameters/promptId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromptTypeUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The prompt's type.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "promptType": {
                          "type": "string",
                          "enum": [
                            "UNBRANDED",
                            "BRANDED",
                            "RECALL"
                          ]
                        },
                        "promptTypeSource": {
                          "type": "string",
                          "enum": [
                            "classifier",
                            "user"
                          ]
                        }
                      },
                      "required": [
                        "id",
                        "promptType",
                        "promptTypeSource"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "c4fdd333-0f2f-49d4-9ccf-5740eae5d56b",
                    "promptType": "BRANDED",
                    "promptTypeSource": "user"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "A change to or from `RECALL`. `error.details.code` is `recall_locked`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/prompts/{promptId}/language": {
      "patch": {
        "operationId": "updateAuditPromptLanguage",
        "summary": "Set a prompt's language",
        "description": "Changes the language a prompt is asked in. A prompt that has been answered is replaced rather than changed, so its history stays in past snapshots: the response's `id` is then the new prompt and `replacedPromptId` the old one.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "$ref": "#/components/parameters/promptId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromptLanguageUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The prompt now carrying the language.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "language": {
                          "type": "string"
                        },
                        "replacedPromptId": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "selected": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "id",
                        "language",
                        "replacedPromptId",
                        "selected"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "c4fdd333-0f2f-49d4-9ccf-5740eae5d56b",
                    "language": "EN",
                    "replacedPromptId": null,
                    "selected": true
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is running. Prompts can be edited only while it is AWAITING_CONFIG, AWAITING_PROMPTS, COMPLETED or FAILED.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "The prompt is an answered recall probe, whose language is fixed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/prompts/{promptId}/edit": {
      "post": {
        "operationId": "editAuditPrompt",
        "summary": "Rewrite a prompt",
        "description": "Changes a prompt's text. An unanswered prompt is edited in place. An answered one is archived with its history and a new prompt takes its place, keeping its selection: the response's `id` is then the new prompt and `parentId` the old one, otherwise `null`.",
        "tags": [
          "prompts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "$ref": "#/components/parameters/promptId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromptEditRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The prompt now carrying the text.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "parentId": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "selected": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "id",
                        "parentId",
                        "selected"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "c4fdd333-0f2f-49d4-9ccf-5740eae5d56b",
                    "parentId": null,
                    "selected": true
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is running — prompts are locked until it finishes, the prompt was already removed or replaced (`error.details.code` `archived`), or another live prompt already asks this text (`duplicate`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/topics": {
      "get": {
        "operationId": "listAuditTopics",
        "summary": "List an audit's topics",
        "description": "Every topic with how many prompts it holds, plus the count filed under none.",
        "tags": [
          "topics"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The topics.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "topics": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "sourceTopicId": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The catalog topic it was created from, if any."
                              },
                              "sortOrder": {
                                "type": "integer"
                              },
                              "active": {
                                "type": "integer",
                                "description": "Live prompts filed under it."
                              },
                              "archived": {
                                "type": "integer",
                                "description": "Archived prompts filed under it."
                              }
                            },
                            "required": [
                              "id",
                              "label",
                              "active",
                              "archived"
                            ],
                            "additionalProperties": true
                          }
                        },
                        "unassigned": {
                          "type": "integer",
                          "description": "Live prompts filed under no topic."
                        },
                        "max": {
                          "type": "integer",
                          "description": "How many topics an audit may have."
                        }
                      },
                      "required": [
                        "topics",
                        "unassigned",
                        "max"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "topics": [
                      {
                        "id": "05a00b07-68bd-4d8d-a29e-cc4359f43f28",
                        "label": "Pricing",
                        "sourceTopicId": null,
                        "sortOrder": 1,
                        "active": 0,
                        "archived": 0
                      }
                    ],
                    "unassigned": 3,
                    "max": 100
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "post": {
        "operationId": "createAuditTopic",
        "summary": "Create a topic",
        "description": "Adds an empty topic. An audit may have at most 100.",
        "tags": [
          "topics"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TopicLabelRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The new topic.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/AuditTopic"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "topic": {
                      "id": "05a00b07-68bd-4d8d-a29e-cc4359f43f28",
                      "label": "Pricing"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "A topic with that label already exists. `error.details` is `{ error: \"topic_exists\", topicId }`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "The audit already has 100 topics. `error.details` is `{ error: \"topic_cap\", max }`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/topics/{topicId}": {
      "patch": {
        "operationId": "renameAuditTopic",
        "summary": "Rename a topic",
        "description": "Changes the label. The prompts filed under it stay where they are.",
        "tags": [
          "topics"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "$ref": "#/components/parameters/topicId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TopicLabelRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The renamed topic.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/AuditTopic"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "topic": {
                      "id": "05a00b07-68bd-4d8d-a29e-cc4359f43f28",
                      "label": "Pricing plans"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "A topic with that label already exists. `error.details` is `{ error: \"topic_exists\", topicId }`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "delete": {
        "operationId": "deleteAuditTopic",
        "summary": "Delete an empty topic",
        "description": "Deletes a topic that holds no prompts, live or archived. To retire one that does, merge it instead.",
        "tags": [
          "topics"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "$ref": "#/components/parameters/topicId"
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted. No body."
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The topic still holds prompts. `error.details` is `{ error: \"topic_in_use\", total, prompts }`, where `prompts` is a sample of `{ id, text }`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "none"
      }
    },
    "/audits/{auditId}/topics/{topicId}/merge": {
      "post": {
        "operationId": "mergeAuditTopic",
        "summary": "Merge a topic into another",
        "description": "Moves every prompt of this topic into `intoTopicId` — or into no topic, when it is `null` — and deletes this one.",
        "tags": [
          "topics"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "$ref": "#/components/parameters/topicId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TopicMergeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The receiving topic and how many prompts moved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "topic": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "label": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "id",
                            "label"
                          ],
                          "additionalProperties": true
                        },
                        "moved": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "topic",
                        "moved"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "topic": null,
                    "moved": 3
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "The target is this topic itself, or not a topic of this audit (`error.details` is `{ error: \"unknown_topic\", topicId }`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/prompts/topic": {
      "patch": {
        "operationId": "assignAuditPromptTopic",
        "summary": "File prompts under a topic",
        "description": "Moves the named prompts into one topic, or into none. All or nothing.",
        "tags": [
          "topics"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromptTopicAssignRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "How many prompts changed topic.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "updated": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "updated"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "updated": 3
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "The topic is not one of this audit's (`{ error: \"unknown_topic\", topicId }`), or some ids are not its prompts (`{ error: \"unknown_prompts\", queryIds }`), in `error.details`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/first-party-terms": {
      "get": {
        "operationId": "listAuditFirstPartyTerms",
        "summary": "List first-party terms",
        "description": "One page of terms, best performers first, with counts per source.",
        "tags": [
          "first-party-terms"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "description": "Only terms from this source. An unknown value lists every source.",
            "schema": {
              "type": "string",
              "enum": [
                "ads_csv",
                "ads_api",
                "gsc"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Only terms containing this text. Cut to 200 characters.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, from 1. Anything else is page 1.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "required": false,
            "description": "Page size. Defaults to and is capped at 50.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of terms.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "source": {
                                "type": "string",
                                "enum": [
                                  "ads_csv",
                                  "ads_api",
                                  "gsc"
                                ]
                              },
                              "term": {
                                "type": "string"
                              },
                              "question": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The term written as a question; `null` until written, or when none was asked for."
                              },
                              "rewriting": {
                                "type": "boolean",
                                "description": "A rewrite was asked for and has not landed yet."
                              },
                              "clicks": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "impressions": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "conversions": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "costMicros": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "description": "Spend in millionths of `currency`."
                              },
                              "currency": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "promptId": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The live prompt made from this term, if any."
                              }
                            },
                            "required": [
                              "id",
                              "source",
                              "term",
                              "question",
                              "rewriting",
                              "promptId"
                            ],
                            "additionalProperties": true
                          }
                        },
                        "total": {
                          "type": "integer",
                          "description": "Terms matching the filters, across all pages."
                        },
                        "bySource": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "source": {
                                "type": "string",
                                "enum": [
                                  "ads_csv",
                                  "ads_api",
                                  "gsc"
                                ]
                              },
                              "count": {
                                "type": "integer"
                              }
                            },
                            "required": [
                              "source",
                              "count"
                            ],
                            "additionalProperties": true
                          },
                          "description": "Matching terms per source, ignoring the `source` filter."
                        },
                        "refreshing": {
                          "type": "boolean",
                          "description": "A connected source is being re-pulled; read again shortly."
                        }
                      },
                      "required": [
                        "items",
                        "total",
                        "bySource",
                        "refreshing"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "items": [
                      {
                        "id": "80e3d716-4612-439c-a35f-aa72445b6c3e",
                        "source": "ads_csv",
                        "term": "widget software for agencies",
                        "question": null,
                        "rewriting": false,
                        "clicks": 12,
                        "impressions": 340,
                        "conversions": 2,
                        "costMicros": 45200000,
                        "currency": "USD",
                        "promptId": null
                      }
                    ],
                    "total": 1,
                    "bySource": [
                      {
                        "source": "ads_csv",
                        "count": 1
                      }
                    ],
                    "refreshing": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/first-party-terms/import": {
      "post": {
        "operationId": "importAuditFirstPartyTerms",
        "summary": "Import a Google Ads search-terms report",
        "description": "Stores the terms from a Google Ads search-terms CSV. It replaces the previous upload's terms that were never made into prompts; the others stay. Terms that look like personal data (an email, phone number or street address) are dropped and counted.",
        "tags": [
          "first-party-terms"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FirstPartyTermsImportRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "What the file held and what was stored.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "found": {
                          "type": "integer",
                          "description": "Data rows read — one per term per campaign or ad group, so above `upserted`."
                        },
                        "skippedRows": {
                          "type": "integer",
                          "description": "Rows with no search term."
                        },
                        "hasConversions": {
                          "type": "boolean",
                          "description": "The file had a Conversions column; without it terms rank by clicks."
                        },
                        "upserted": {
                          "type": "integer",
                          "description": "Distinct terms stored."
                        },
                        "withConversions": {
                          "type": "integer"
                        },
                        "skippedPii": {
                          "type": "integer"
                        },
                        "skippedInvalid": {
                          "type": "integer",
                          "description": "Terms no prompt could be: too short, too long, or blank."
                        }
                      },
                      "required": [
                        "found",
                        "skippedRows",
                        "hasConversions",
                        "upserted",
                        "withConversions",
                        "skippedPii",
                        "skippedInvalid"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "found": 1,
                    "skippedRows": 0,
                    "hasConversions": true,
                    "upserted": 1,
                    "withConversions": 1,
                    "skippedPii": 0,
                    "skippedInvalid": 0
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is running. Prompts can be edited only while it is AWAITING_CONFIG, AWAITING_PROMPTS, COMPLETED or FAILED.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "The file is not a Google Ads search-terms report.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/first-party-terms/select": {
      "post": {
        "operationId": "selectAuditFirstPartyTerms",
        "summary": "Turn terms into prompts",
        "description": "Adds up to 100 terms as prompts, using each one's question when it has one. Terms that repeat each other or an existing prompt are skipped; prompts past the plan's capacity are added unselected.",
        "tags": [
          "first-party-terms"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FirstPartyTermsSelectRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The prompt list after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "prompts": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Prompt"
                          }
                        },
                        "maxQueries": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "added": {
                          "type": "integer",
                          "description": "Prompts inserted."
                        },
                        "skippedDuplicates": {
                          "type": "integer"
                        },
                        "overCap": {
                          "type": "integer",
                          "description": "Inserted prompts left unselected past the plan's capacity."
                        }
                      },
                      "required": [
                        "prompts",
                        "maxQueries",
                        "added",
                        "skippedDuplicates",
                        "overCap"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "prompts": [
                      {
                        "id": "0f4d5c46-b98e-4854-af39-2f6c7a32c038",
                        "text": "best widget software for small teams",
                        "selected": true,
                        "angleId": "CUSTOM",
                        "language": null,
                        "promptType": "UNBRANDED",
                        "topicId": null,
                        "region": null,
                        "querySubject": "OFFERING",
                        "funnelStage": null,
                        "angleLabel": "Custom",
                        "isCustom": true,
                        "branded": false
                      },
                      {
                        "id": "a3985077-683f-4df2-9b51-6474baab91e2",
                        "text": "how do I choose a widget vendor",
                        "selected": true,
                        "angleId": "CUSTOM",
                        "language": null,
                        "promptType": "UNBRANDED",
                        "topicId": null,
                        "region": null,
                        "querySubject": "OFFERING",
                        "funnelStage": null,
                        "angleLabel": "Custom",
                        "isCustom": true,
                        "branded": false
                      }
                    ],
                    "maxQueries": 25,
                    "added": 1,
                    "skippedDuplicates": 0,
                    "overCap": 0
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is running. Prompts can be edited only while it is AWAITING_CONFIG, AWAITING_PROMPTS, COMPLETED or FAILED.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/first-party-terms/{termId}/dismiss": {
      "post": {
        "operationId": "dismissAuditFirstPartyTerm",
        "summary": "Dismiss a term",
        "description": "Hides a term from the list. A connected source's later pulls keep it hidden, but a new Ads report upload replaces every term never made a prompt, so a dismissed term in it comes back.",
        "tags": [
          "first-party-terms"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "termId",
            "in": "path",
            "required": true,
            "description": "The term's id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Dismissed. No body."
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is running. Prompts can be edited only while it is AWAITING_CONFIG, AWAITING_PROMPTS, COMPLETED or FAILED.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "none"
      }
    },
    "/audits/{auditId}/start": {
      "post": {
        "operationId": "startConfiguredAudit",
        "summary": "Start a configured audit",
        "description": "The normal way to begin measuring: send the configuration (connectors, model, languages, locations, angles) and the run is enqueued. Answers **202** with an estimate of the run's size plus the connector sets actually used — `effectiveConnectors` and `droppedConnectors` tell you what the plan clamped, which is why they are worth reading rather than assuming your selection was honoured verbatim.\n\n**This starts paid work.** Poll `GET /audits/{auditId}/run` for progress; do not call this again to check on it. A 422 means the configuration was rejected — read the error message rather than retrying.\n\n**Requires `status` to be `AWAITING_CONFIG` or `AWAITING_PROMPTS`**, and answers 409 otherwise — either because a run is already in flight, or because the audit was never prepared. A newly created audit is `PENDING`: call `POST /audits/{auditId}/prepare` first and wait for it to reach `AWAITING_CONFIG`.",
        "tags": [
          "runs"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditStartRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The run was enqueued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "auditId": {
                          "type": "string"
                        },
                        "estimate": {
                          "type": "object",
                          "additionalProperties": true,
                          "description": "Estimated run size — query and execution counts."
                        },
                        "effectiveConnectors": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "droppedConnectors": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "auditId"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is not in a startable state: either a run is already in progress, or it has not been prepared and is still PENDING.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "The configuration was rejected — see the error message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "authored"
      }
    },
    "/audits/{auditId}/run": {
      "post": {
        "operationId": "startAuditRun",
        "summary": "Start or resume a run directly",
        "description": "The lower-level entry point to running an audit: it resumes and re-measures rather than re-asking the AI connectors for angles that already completed. Answers **202**.\n\nPrefer `POST /audits/{auditId}/start` for a normal integration — it takes the audit's configuration and reports what the plan clamped. Reach for this one when you need to override run mechanics (crawl policy, snapshot behaviour, a specific angle subset).\n\n**This starts paid work.** By default completed angles are not re-asked. Send `refreshAnswers: true` to re-ask the AI connectors for a `COMPLETED` audit — the full paid cost of a run; it is ignored for an audit in any other status, which resumes instead. `forceRecover` exists only to unstick a wedged run; a genuinely stale one recovers on its own without it.",
        "tags": [
          "runs"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditRunRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The run was enqueued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "auditId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "startedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "options": {
                          "type": "object",
                          "additionalProperties": true,
                          "description": "The options the run was started with, after clamping."
                        }
                      },
                      "required": [
                        "auditId",
                        "status"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "A run is already in progress for this audit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "authored"
      },
      "get": {
        "operationId": "getAuditRun",
        "summary": "Poll a run's status",
        "description": "The poll endpoint for an asynchronous run. `runStatus` is the run's own state and `auditStatus` the audit's; `laneProgress` is populated only while collecting. **Respect `retryAfterMs`** — it is the server's guidance on when to poll next, and it varies with the phase the run is in. It is `null` once `runStatus` is `COMPLETED` or `FAILED`: stop polling. Polling faster does not make a run finish sooner, and this endpoint is rate-limited like any other.",
        "tags": [
          "runs"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The run's status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "auditId": {
                          "type": "string"
                        },
                        "runStatus": {
                          "type": "string"
                        },
                        "auditStatus": {
                          "type": "string"
                        },
                        "laneProgress": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "additionalProperties": true,
                          "description": "Per-lane progress counters. Present only while collecting."
                        },
                        "startedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "options": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "additionalProperties": true,
                          "description": "The options the run was started with."
                        },
                        "error": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "retryAfterMs": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "auditId",
                        "runStatus",
                        "auditStatus",
                        "retryAfterMs"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "auditId": "clrecorderaudit0000000001",
                    "runStatus": "COMPLETED",
                    "auditStatus": "COMPLETED",
                    "laneProgress": null,
                    "startedAt": null,
                    "options": null,
                    "error": null,
                    "updatedAt": "2026-10-26T19:53:04.847Z",
                    "retryAfterMs": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/snapshots": {
      "get": {
        "operationId": "listAuditSnapshots",
        "summary": "List an audit's snapshots",
        "description": "The snapshot history, newest first, cursor-paginated — the cheapest way to watch an audit over time, and the right endpoint to poll. Each item carries summary metrics and `reportAvailable`, which tells you whether that snapshot can hydrate a report. The per-segment `overviewCube` is the one heavy field and is omitted unless you ask for it with `?include=overviewCube`, which keeps a page bounded. Note the response sets `Cache-Control: private, no-store`, because it includes mutable state (the snapshot pause toggle and manual-run eligibility).",
        "tags": [
          "results"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Defaults to 50, capped at 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "description": "Newest first (`desc`, the default) or oldest first (`asc`).",
            "schema": {
              "default": "desc",
              "type": "string",
              "enum": [
                "desc",
                "asc"
              ]
            }
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "description": "Comma-separated heavy fields to include: overviewCube.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque cursor from a previous response's `nextCursor`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of snapshots.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "snapshots": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "label": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "type": {
                                "type": "string",
                                "enum": [
                                  "full",
                                  "short"
                                ]
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "connectorTypes": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "alerts": {
                                "type": [
                                  "array",
                                  "null"
                                ],
                                "items": {
                                  "type": "object",
                                  "additionalProperties": true,
                                  "description": "A short-snapshot alert."
                                }
                              },
                              "metrics": {
                                "type": [
                                  "object",
                                  "null"
                                ],
                                "additionalProperties": true,
                                "description": "Summary metrics for this snapshot."
                              },
                              "durationMs": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "reportAvailable": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "id",
                              "type",
                              "createdAt",
                              "reportAvailable"
                            ],
                            "additionalProperties": true
                          }
                        },
                        "nextCursor": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "schedule": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "intervalHours": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "nextRunAt": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "snapshotEnabled": {
                              "type": "boolean"
                            }
                          },
                          "additionalProperties": true
                        },
                        "scheduleAvailable": {
                          "type": "boolean"
                        },
                        "manualRun": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "eligible": {
                              "type": "boolean"
                            },
                            "nextEligibleAt": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "reason": {
                              "type": "string",
                              "enum": [
                                "ok",
                                "cooldown",
                                "auto_plan",
                                "period_run_cap"
                              ]
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "snapshots",
                        "nextCursor"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "snapshots": [
                      {
                        "id": "00000000-0000-4000-8000-00000000e102",
                        "label": null,
                        "type": "full",
                        "createdAt": "2026-10-25T19:53:04.851Z",
                        "connectorTypes": [],
                        "metrics": {
                          "ccrScore": 0.4,
                          "overview": {
                            "visibility": 0.62
                          },
                          "sbaScore": 0.5,
                          "marketTrend": null,
                          "shareOfVoice": [
                            {
                              "name": "…",
                              "share": "…",
                              "isBrand": "…"
                            },
                            {
                              "name": "…",
                              "share": "…",
                              "isBrand": "…"
                            }
                          ],
                          "visibilityScore": 0.62,
                          "brandMentionCount": 12,
                          "visibilityCompetitors": null
                        },
                        "durationMs": null,
                        "reportAvailable": true,
                        "alerts": null
                      },
                      {
                        "id": "00000000-0000-4000-8000-00000000e101",
                        "label": null,
                        "type": "full",
                        "createdAt": "2026-10-18T19:53:04.849Z",
                        "connectorTypes": [],
                        "metrics": {
                          "ccrScore": 0.4,
                          "overview": {
                            "visibility": 0.62
                          },
                          "sbaScore": 0.5,
                          "marketTrend": null,
                          "shareOfVoice": [
                            {
                              "name": "…",
                              "share": "…",
                              "isBrand": "…"
                            },
                            {
                              "name": "…",
                              "share": "…",
                              "isBrand": "…"
                            }
                          ],
                          "visibilityScore": 0.62,
                          "brandMentionCount": 12,
                          "visibilityCompetitors": null
                        },
                        "durationMs": null,
                        "reportAvailable": false,
                        "alerts": null
                      }
                    ],
                    "nextCursor": null,
                    "schedule": null,
                    "scheduleAvailable": true,
                    "manualRun": {
                      "eligible": false,
                      "nextEligibleAt": null,
                      "reason": "auto_plan"
                    },
                    "forcedRunAvailable": true
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "post": {
        "operationId": "createAuditSnapshot",
        "summary": "Take a snapshot",
        "description": "Freezes the audit's current results as a snapshot, to compare against later — before a site change, say. Asks no AI surface; it records what the last run measured. `baselineSnapshotId` names the snapshot a later compare measures it against.",
        "tags": [
          "results"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SnapshotCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The new snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "snapshotId": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "snapshotId"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is not COMPLETED, or it has no report to freeze yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/snapshots/compare": {
      "get": {
        "operationId": "compareAuditSnapshots",
        "summary": "Compare two snapshots",
        "description": "What moved between two snapshots of an audit: prompts, per-answer metrics, competitors, cited sources and the report's recommendations. Omit `a` to compare `b` with the baseline it was taken against. The two longest lists are capped; their totals stay exact. Send the `ETag` back as `If-None-Match` to get a **304** while nothing changed.",
        "tags": [
          "results"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "a",
            "in": "query",
            "required": false,
            "description": "The earlier snapshot. Omit it to compare `b` with its own baseline.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "b",
            "in": "query",
            "required": false,
            "description": "The later snapshot.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The diff.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/SnapshotDiff"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "304": {
            "description": "Unchanged since the `ETag` you sent. No body."
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/optimizations/progress": {
      "get": {
        "operationId": "getAuditOptimizationsProgress",
        "summary": "Read optimization progress",
        "description": "What moved since the baseline: the newest snapshot taken against a baseline (or the one `snapshotId` names), diffed against that baseline, plus every winnable prompt of the pair, changed or not. `diff` is `null` and `allWinnableQueries` empty until a snapshot names a baseline. Send the `ETag` back as `If-None-Match` to get a **304** while nothing changed.",
        "tags": [
          "results"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "snapshotId",
            "in": "query",
            "required": false,
            "description": "The snapshot to read. Omit it for the newest snapshot taken against a baseline.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The progress.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "latestSnapshotId": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "baselineSnapshotId": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "diff": {
                          "anyOf": [
                            {
                              "$ref": "#/components/schemas/SnapshotDiff"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "allWinnableQueries": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "description": "A winnable prompt with its score and coverage on both sides."
                          }
                        }
                      },
                      "required": [
                        "latestSnapshotId",
                        "baselineSnapshotId",
                        "diff",
                        "allWinnableQueries"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "304": {
            "description": "Unchanged since the `ETag` you sent. No body."
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/snapshots/{snapshotId}/alerts": {
      "get": {
        "operationId": "getAuditSnapshotAlerts",
        "summary": "Read a snapshot's alerts",
        "description": "The changes a snapshot raised against the one before it — a new competitor, a metric delta, a rank move, a blocked crawler — at most 80. Each `type` carries its own fields. A snapshot's alerts never change once written.",
        "tags": [
          "results"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "snapshotId",
            "in": "path",
            "required": true,
            "description": "The snapshot's id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The alerts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "auditId": {
                          "type": "string"
                        },
                        "auditLabel": {
                          "type": "string"
                        },
                        "snapshotId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "alerts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": [
                                  "new_competitor",
                                  "entity_disappeared",
                                  "new_citation_source",
                                  "metric_delta",
                                  "rank_move",
                                  "striking_distance_entry",
                                  "ai_referral_delta",
                                  "edge_blocked_crawler"
                                ]
                              },
                              "entityName": {
                                "type": "string"
                              },
                              "domain": {
                                "type": "string"
                              },
                              "metric": {
                                "type": "string"
                              },
                              "before": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "after": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "delta": {
                                "type": "number"
                              },
                              "keyword": {
                                "type": "string"
                              },
                              "tier": {
                                "type": "string",
                                "enum": [
                                  "almost_there",
                                  "page_two"
                                ]
                              },
                              "bot": {
                                "type": "string"
                              },
                              "requests": {
                                "type": "integer"
                              },
                              "blockedRequests": {
                                "type": "integer"
                              },
                              "basis": {
                                "type": "string",
                                "enum": [
                                  "robots_contradiction",
                                  "live_fetch_refused"
                                ]
                              }
                            },
                            "required": [
                              "type"
                            ],
                            "additionalProperties": true
                          }
                        }
                      },
                      "required": [
                        "auditId",
                        "auditLabel",
                        "snapshotId",
                        "createdAt",
                        "alerts"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "auditId": "clrecorderaudit0000000001",
                    "auditLabel": "example.com",
                    "snapshotId": "00000000-0000-4000-8000-00000000e102",
                    "createdAt": "2026-10-25T19:53:04.851Z",
                    "alerts": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/answers/export": {
      "get": {
        "operationId": "exportAuditAnswers",
        "summary": "Export answers",
        "description": "Every answer received between `from` and `to`, one row each, newest first — the raw material behind the report. Pages hold up to 5000 rows; pass `nextCursor` back as `cursor` until it is `null`. A range spans at most 366 days.",
        "tags": [
          "results"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "from",
            "in": "query",
            "required": true,
            "description": "First day of answers to include, `YYYY-MM-DD` (UTC).",
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "description": "Last day to include, `YYYY-MM-DD` (UTC). At most 366 days after `from`.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque cursor from a previous page's `nextCursor`.",
            "schema": {
              "type": "string",
              "maxLength": 512
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Rows per page.",
            "schema": {
              "default": 1000,
              "type": "integer",
              "minimum": 1,
              "maximum": 5000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of answers.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "rows": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "answerId": {
                                "type": "string"
                              },
                              "runAt": {
                                "type": "string",
                                "format": "date-time",
                                "description": "When the answer was received, UTC."
                              },
                              "snapshotId": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The earliest snapshot holding this answer; `null` until one does."
                              },
                              "prompt": {
                                "type": "string"
                              },
                              "promptType": {
                                "type": "string",
                                "enum": [
                                  "UNBRANDED",
                                  "BRANDED",
                                  "RECALL"
                                ]
                              },
                              "topic": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "angle": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "firstPartySource": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "enum": [
                                  "ads_csv",
                                  "ads_api",
                                  "gsc",
                                  null
                                ]
                              },
                              "firstPartyTerm": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "engine": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The connector that asked, e.g. `OPENAI`."
                              },
                              "lane": {
                                "type": "string",
                                "description": "What was measured, e.g. `CHATGPT` or `CHATGPT:gpt-5`."
                              },
                              "mentioned": {
                                "type": [
                                  "boolean",
                                  "null"
                                ]
                              },
                              "position": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "citationCount": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "brandCitationCount": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "sentiment": {
                                "type": [
                                  "number",
                                  "null"
                                ],
                                "description": "Sentiment of the sentences naming the brand, 0–1."
                              },
                              "offTopic": {
                                "type": "boolean",
                                "description": "The report leaves this answer out of its counts."
                              }
                            },
                            "required": [
                              "answerId",
                              "runAt",
                              "snapshotId",
                              "prompt",
                              "promptType",
                              "topic",
                              "angle",
                              "firstPartySource",
                              "firstPartyTerm",
                              "engine",
                              "lane",
                              "mentioned",
                              "position",
                              "citationCount",
                              "brandCitationCount",
                              "sentiment",
                              "offTopic"
                            ],
                            "additionalProperties": true
                          }
                        },
                        "nextCursor": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "rows",
                        "nextCursor"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "rows": [
                      {
                        "answerId": "clrecorderanswer000000001",
                        "runAt": "2026-10-25T19:53:04.860Z",
                        "snapshotId": null,
                        "prompt": "what is the best widget software",
                        "promptType": "UNBRANDED",
                        "topic": null,
                        "angle": "Brand Discovery",
                        "firstPartySource": null,
                        "firstPartyTerm": null,
                        "engine": "OPENAI",
                        "lane": "OPENAI",
                        "mentioned": null,
                        "position": null,
                        "citationCount": null,
                        "brandCitationCount": null,
                        "sentiment": null,
                        "offTopic": false
                      }
                    ],
                    "nextCursor": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/answers/export.csv": {
      "get": {
        "operationId": "exportAuditAnswersCsv",
        "summary": "Export answers as CSV",
        "description": "The same rows as `GET /audits/{auditId}/answers/export`, as a CSV download with snake_case headers. Past 10000 rows the file ends with a `# truncated` line and the `X-Beket-Truncated` header is set; page the JSON export for the rest.",
        "tags": [
          "results"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "from",
            "in": "query",
            "required": true,
            "description": "First day of answers to include, `YYYY-MM-DD` (UTC).",
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "description": "Last day to include, `YYYY-MM-DD` (UTC). At most 366 days after `from`.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The answers as a CSV file, UTF-8 with a byte-order mark.",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "none"
      }
    },
    "/audits/{auditId}/synthesis": {
      "get": {
        "operationId": "getAuditSynthesisStatus",
        "summary": "Check whether the report is written",
        "description": "The audit's status and whether its written analysis exists yet — the cheap poll after a regenerate.",
        "tags": [
          "results"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        },
                        "llm": {
                          "type": "boolean",
                          "description": "The written analysis exists."
                        }
                      },
                      "required": [
                        "status",
                        "llm"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "status": "COMPLETED",
                    "llm": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/synthesis/run": {
      "post": {
        "operationId": "runAuditSynthesis",
        "summary": "Write the report",
        "description": "Writes the report's analysis over the metrics the last run computed, without asking the AI surfaces again. Answers **202**; poll `GET /audits/{auditId}/synthesis`. **This starts paid work.**",
        "tags": [
          "results"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "202": {
            "description": "Started.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "auditId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "const": "SYNTHESIZING_AUDIT"
                        }
                      },
                      "required": [
                        "auditId",
                        "status"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is running. It must be COMPLETED or FAILED.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "authored"
      }
    },
    "/audits/{auditId}/synthesis/regenerate": {
      "post": {
        "operationId": "regenerateAuditSynthesis",
        "summary": "Recompute the report",
        "description": "Recomputes the metrics from the stored answers and rewrites the report — after a change to competitors, say. No AI surface is asked again. A market audit rebuilds its leaderboard instead. Answers **202**; poll `GET /audits/{auditId}/synthesis`. **This starts paid work.**",
        "tags": [
          "results"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "202": {
            "description": "Started.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/RecomputeJob"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit is running. It must be COMPLETED or FAILED.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "authored"
      }
    },
    "/audits/{auditId}/metrics/compute": {
      "post": {
        "operationId": "computeAuditMetrics",
        "summary": "Recompute the metrics",
        "description": "Recomputes the metrics from the stored answers without rewriting the report or asking the AI surfaces again, and costs nothing. Answers **202**; poll `GET /audits/{auditId}/synthesis` until the status is back to `COMPLETED`. A market audit rebuilds through `POST /audits/{auditId}/synthesis/regenerate` instead.",
        "tags": [
          "results"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "202": {
            "description": "Started.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/RecomputeJob"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "A run or a report rebuild is already in progress.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/analytics/portfolio": {
      "get": {
        "operationId": "getPortfolioAnalytics",
        "summary": "Get the portfolio roll-up",
        "description": "Totals across every audit in your organization, aggregated in the database rather than assembled client-side. **Bounded by design:** it returns portfolio totals and at most ten competitors. For per-audit detail, use the single-audit endpoints — this one will not grow to carry it.",
        "tags": [
          "results"
        ],
        "parameters": [
          {
            "name": "entityId",
            "in": "query",
            "required": false,
            "description": "Restrict the roll-up to one entity.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Restrict the roll-up to one domain.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "take",
            "in": "query",
            "required": false,
            "description": "How many audits to aggregate. Defaults to 50, capped at 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The portfolio roll-up.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "auditCount": {
                          "type": "integer"
                        },
                        "aggregates": {
                          "type": "object",
                          "properties": {
                            "totalMentions": {
                              "type": "integer"
                            },
                            "totalWinnableQueries": {
                              "type": "integer"
                            },
                            "topCompetitors": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "name": {
                                    "type": "string"
                                  },
                                  "mentions": {
                                    "type": "number"
                                  }
                                },
                                "required": [
                                  "name",
                                  "mentions"
                                ],
                                "additionalProperties": true
                              }
                            }
                          },
                          "required": [
                            "totalMentions",
                            "totalWinnableQueries",
                            "topCompetitors"
                          ],
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "auditCount",
                        "aggregates"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "auditCount": 1,
                    "aggregates": {
                      "totalMentions": 0,
                      "totalWinnableQueries": 0,
                      "topCompetitors": []
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/citations": {
      "get": {
        "operationId": "listAuditCitations",
        "summary": "List cited sources",
        "description": "How many URLs the current answers cited, the 10 most-cited domains with exact counts, and — with `include=items` — up to 100 of the URLs themselves, newest first.",
        "tags": [
          "sources"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "verified",
            "in": "query",
            "required": false,
            "description": "`true` lists only sources whose URL was verified, any other value only unverified ones. Omit it for both.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "description": "`items` adds up to 100 cited URLs, newest first. Without it the response carries only `total` and `domains`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The cited sources.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer"
                        },
                        "domains": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "domain": {
                                "type": "string"
                              },
                              "count": {
                                "type": "integer"
                              },
                              "sampleUrl": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "domain",
                              "count",
                              "sampleUrl"
                            ],
                            "additionalProperties": true
                          },
                          "description": "At most 10, most cited first."
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "auditId": {
                                "type": "string"
                              },
                              "answerId": {
                                "type": "string"
                              },
                              "url": {
                                "type": "string"
                              },
                              "normalizedUrl": {
                                "type": "string"
                              },
                              "domain": {
                                "type": "string"
                              },
                              "connectorType": {
                                "type": "string"
                              },
                              "verificationStartedAt": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "format": "date-time"
                              },
                              "verifiedAt": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "format": "date-time",
                                "description": "When the URL was checked; `null` until it is."
                              },
                              "httpStatus": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "resolves": {
                                "type": [
                                  "boolean",
                                  "null"
                                ]
                              },
                              "isRelevant": {
                                "type": [
                                  "boolean",
                                  "null"
                                ]
                              },
                              "relevanceScore": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "verificationMethod": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "sourceType": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "What kind of site it is, as classified or overridden."
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              }
                            },
                            "required": [
                              "id",
                              "url",
                              "domain",
                              "connectorType",
                              "verifiedAt",
                              "createdAt"
                            ],
                            "additionalProperties": true
                          },
                          "description": "Only with `include=items`; at most 100."
                        }
                      },
                      "required": [
                        "total",
                        "domains"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "items": [
                      {
                        "id": "d0b67a7d-8670-47de-9bec-eab71915b3d0",
                        "auditId": "clrecorderaudit0000000001",
                        "answerId": "clrecorderanswer000000001",
                        "url": "https://rival.com/widgets",
                        "normalizedUrl": "https://rival.com/widgets",
                        "domain": "rival.com",
                        "connectorType": "OPENAI",
                        "verificationStartedAt": null,
                        "verifiedAt": null,
                        "httpStatus": null,
                        "resolves": null,
                        "isRelevant": null,
                        "relevanceScore": null,
                        "verificationMethod": null,
                        "sourceType": null,
                        "createdAt": "2026-10-26T19:53:04.861Z"
                      }
                    ],
                    "total": 1,
                    "domains": [
                      {
                        "domain": "rival.com",
                        "count": 1,
                        "sampleUrl": "https://rival.com/widgets"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/sources/overrides": {
      "get": {
        "operationId": "listSourceTypeOverrides",
        "summary": "List source-type overrides",
        "description": "The source types your organization set by hand — a host or path classified as a forum, a review site and so on. They apply to every audit in the organization.",
        "tags": [
          "sources"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The overrides.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "overrides": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/SourceTypeOverride"
                          }
                        },
                        "max": {
                          "type": "integer",
                          "description": "Always 500."
                        }
                      },
                      "required": [
                        "overrides",
                        "max"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "overrides": [
                      {
                        "domain": "reviews.example.org",
                        "pathPrefix": "",
                        "sourceType": "review_site",
                        "updatedAt": "2026-10-26T19:53:05.381Z"
                      }
                    ],
                    "max": 500
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit belongs to no organization, so it has no overrides.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "put": {
        "operationId": "setSourceTypeOverride",
        "summary": "Set a source-type override",
        "description": "Classifies a host, `host/path` or URL as `sourceType` for every audit in the organization, replacing any override on the same target. Whether a site is the brand's or a competitor's is decided by the audit and cannot be overridden.",
        "tags": [
          "sources"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SourceTypeOverrideRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The override as stored.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "override": {
                          "$ref": "#/components/schemas/SourceTypeOverride"
                        }
                      },
                      "required": [
                        "override"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "override": {
                      "domain": "reviews.example.org",
                      "pathPrefix": "",
                      "sourceType": "review_site",
                      "updatedAt": "2026-10-26T19:53:05.381Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit belongs to no organization, so it has no overrides.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "The organization already has 500 overrides.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "delete": {
        "operationId": "deleteSourceTypeOverride",
        "summary": "Remove a source-type override",
        "description": "Removes the override on `target`. Removing one that does not exist succeeds.",
        "tags": [
          "sources"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "target",
            "in": "query",
            "required": true,
            "description": "The override to remove: a host, `host/path` or URL, as it was set.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2048
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Removed. No body."
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The audit belongs to no organization, so it has no overrides.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "none"
      }
    },
    "/audits/{auditId}/sources/watch": {
      "get": {
        "operationId": "listCitationWatches",
        "summary": "List watched domains",
        "description": "The cited hosts this audit's team pinned to keep an eye on.",
        "tags": [
          "sources"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The watched domains.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "watches": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "domain": {
                                "type": "string"
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              }
                            },
                            "required": [
                              "domain",
                              "createdAt"
                            ],
                            "additionalProperties": true
                          }
                        },
                        "max": {
                          "type": "integer",
                          "description": "Always 25."
                        }
                      },
                      "required": [
                        "watches",
                        "max"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "watches": [
                      {
                        "domain": "rival.com",
                        "createdAt": "2026-10-26T19:53:05.398Z"
                      }
                    ],
                    "max": 25
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "put": {
        "operationId": "watchCitationDomain",
        "summary": "Watch a domain",
        "description": "Adds a host to the watch list. Watching one already watched succeeds.",
        "tags": [
          "sources"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CitationWatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The watch.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "watch": {
                          "type": "object",
                          "properties": {
                            "domain": {
                              "type": "string"
                            },
                            "createdAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "required": [
                            "domain",
                            "createdAt"
                          ],
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "watch"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "watch": {
                      "domain": "rival.com",
                      "createdAt": "2026-10-26T19:53:05.398Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "The audit already watches 25 domains.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "delete": {
        "operationId": "unwatchCitationDomain",
        "summary": "Stop watching a domain",
        "description": "Removes `domain` from the watch list. Removing one not watched succeeds.",
        "tags": [
          "sources"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "The watched host to stop watching.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 253
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Removed. No body."
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "none"
      }
    },
    "/audits/{auditId}/facts": {
      "get": {
        "operationId": "listAuditBrandFacts",
        "summary": "List the brand's facts",
        "description": "The current confirmed facts, the drafts waiting for a decision (newest first, at most 10 per key), and the keys the brand's vertical expects that have no confirmed fact yet.",
        "tags": [
          "facts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The facts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "vertical": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The brand's vertical; `null` reads as general."
                        },
                        "gaps": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "claim",
                              "phone",
                              "address",
                              "hours",
                              "primary_category",
                              "service_area",
                              "headquarters",
                              "founded_year",
                              "founder",
                              "pricing_model",
                              "price_range",
                              "certification",
                              "offering"
                            ]
                          },
                          "description": "Keys the vertical expects with no confirmed fact."
                        },
                        "confirmed": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/BrandFact"
                          }
                        },
                        "drafts": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/BrandFact"
                          }
                        }
                      },
                      "required": [
                        "vertical",
                        "gaps",
                        "confirmed",
                        "drafts"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "vertical": null,
                    "gaps": [
                      "claim",
                      "headquarters"
                    ],
                    "confirmed": [],
                    "drafts": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "post": {
        "operationId": "addAuditBrandFact",
        "summary": "Add a fact",
        "description": "Records a confirmed fact. For a key that holds one value, it replaces the current one, which stays in the history. Sending the current value again changes nothing and answers **200** with `created: false`.",
        "tags": [
          "facts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BrandFactCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The value was already current.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "fact": {
                          "$ref": "#/components/schemas/BrandFact"
                        },
                        "created": {
                          "type": "boolean",
                          "const": false
                        }
                      },
                      "required": [
                        "fact",
                        "created"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "201": {
            "description": "The new fact.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "fact": {
                          "$ref": "#/components/schemas/BrandFact"
                        },
                        "created": {
                          "type": "boolean",
                          "const": true
                        }
                      },
                      "required": [
                        "fact",
                        "created"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "fact": {
                      "id": "84ecd60c-420a-41da-b353-fdb0b1b6dd6f",
                      "factKey": "phone",
                      "value": "+1 555 0100",
                      "sourceUrl": "https://example.com/contact",
                      "origin": "user",
                      "state": "confirmed",
                      "decidedAt": "2026-10-26T19:53:05.413Z",
                      "supersededAt": null,
                      "createdByUserId": null,
                      "createdAt": "2026-10-26T19:53:05.413Z"
                    },
                    "created": true
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The key already holds 100 confirmed values (`fact_limit`), or a concurrent write won (`fact_conflict`) — read and retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/facts/history": {
      "get": {
        "operationId": "listAuditBrandFactHistory",
        "summary": "List a fact's history",
        "description": "Every value one key has held, newest first, 50 per page — replaced, rejected and current alike. Pass `nextCursor` back as `cursor` until it is `null`.",
        "tags": [
          "facts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "factKey",
            "in": "query",
            "required": true,
            "description": "The fact whose history to list.",
            "schema": {
              "type": "string",
              "enum": [
                "claim",
                "phone",
                "address",
                "hours",
                "primary_category",
                "service_area",
                "headquarters",
                "founded_year",
                "founder",
                "pricing_model",
                "price_range",
                "certification",
                "offering"
              ]
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque cursor from a previous page's `nextCursor`.",
            "schema": {
              "type": "string",
              "maxLength": 512
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "facts": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/BrandFact"
                          }
                        },
                        "nextCursor": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "facts",
                        "nextCursor"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "facts": [],
                    "nextCursor": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/facts/{factId}/confirm": {
      "post": {
        "operationId": "confirmAuditBrandFact",
        "summary": "Confirm a draft",
        "description": "Confirms a draft as it is, or — with a `value` — confirms your correction of it instead. Send `{}` to confirm it unchanged.",
        "tags": [
          "facts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "$ref": "#/components/parameters/factId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BrandFactConfirmRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The confirmed fact.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/BrandFactDecision"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "fact": {
                      "id": "c47baa43-276c-45d4-93d5-09a3e26a7580",
                      "factKey": "claim",
                      "value": "Family owned since 1998",
                      "sourceUrl": null,
                      "origin": "places",
                      "state": "confirmed",
                      "decidedAt": "2026-10-26T19:53:05.425Z",
                      "supersededAt": null,
                      "createdByUserId": null,
                      "createdAt": "2026-10-26T19:53:05.421Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The fact is not a pending draft (`fact_decided`), or the key already holds 100 confirmed values (`fact_limit`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/facts/{factId}/reject": {
      "post": {
        "operationId": "rejectAuditBrandFact",
        "summary": "Reject a fact",
        "description": "Rejects a draft, or retracts a current confirmed fact. The value is kept as `rejected`, so no later draft brings it back.",
        "tags": [
          "facts"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "$ref": "#/components/parameters/factId"
          }
        ],
        "responses": {
          "200": {
            "description": "The rejected fact.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/BrandFactDecision"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "fact": {
                      "id": "0cbd0f1b-9921-4eb3-ac83-38789de11596",
                      "factKey": "claim",
                      "value": "Open 24 hours",
                      "sourceUrl": null,
                      "origin": "places",
                      "state": "rejected",
                      "decidedAt": "2026-10-26T19:53:05.437Z",
                      "supersededAt": null,
                      "createdByUserId": null,
                      "createdAt": "2026-10-26T19:53:05.433Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The fact was already superseded or rejected (`fact_decided`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/ai-referral-traffic": {
      "get": {
        "operationId": "getAuditAiReferralTraffic",
        "summary": "Read AI-referred visits",
        "description": "Sessions that arrived from an AI surface (ChatGPT, Perplexity, Gemini…), by day and source over the last 90 days, plus the 50 landing pages they reached most. Empty until a GA4 property is connected and pulled.",
        "tags": [
          "traffic"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The referral series.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "points": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "source": {
                                "type": "string"
                              },
                              "sessions": {
                                "type": "integer"
                              },
                              "reportDate": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "source",
                              "sessions",
                              "reportDate"
                            ],
                            "additionalProperties": true
                          }
                        },
                        "pages": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "landingPage": {
                                "type": "string"
                              },
                              "sessions": {
                                "type": "integer"
                              },
                              "keyEvents": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              }
                            },
                            "required": [
                              "landingPage",
                              "sessions",
                              "keyEvents"
                            ],
                            "additionalProperties": true
                          },
                          "description": "At most 50, most sessions first."
                        },
                        "connectionStatus": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The analytics connection's state; `null` when none is connected."
                        },
                        "connectionUpdatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "lastPull": {
                          "$ref": "#/components/schemas/ReferralPull"
                        }
                      },
                      "required": [
                        "points",
                        "pages",
                        "connectionStatus",
                        "connectionUpdatedAt",
                        "lastPull"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "points": [],
                    "pages": [],
                    "connectionStatus": null,
                    "connectionUpdatedAt": null,
                    "lastPull": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/crawl-diagnostics": {
      "get": {
        "operationId": "getAuditCrawlDiagnostics",
        "summary": "Read AI crawler activity",
        "description": "The last 30 days of AI crawler requests from the connected Cloudflare zone: one row per day, the 50 busiest bots, the 25 most-crawled pages broken down by the 6 busiest crawlers, and the 10 largest referral sources. A day with `crawlPulled: false` was not measured — its `null` counts are unknown, not zero.",
        "tags": [
          "traffic"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The diagnostics.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "connectionStatus": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The analytics connection's state; `null` when none is connected."
                        },
                        "connectionUpdatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "zoneTag": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "referralUnit": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "lastCrawlPullAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "daysCovered": {
                          "type": "integer"
                        },
                        "lastReferralPull": {
                          "$ref": "#/components/schemas/ReferralPull"
                        },
                        "days": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "day": {
                                "type": "string"
                              },
                              "crawlPulled": {
                                "type": "boolean"
                              },
                              "crawlRows": {
                                "type": "integer"
                              },
                              "requests": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "byPurpose": {
                                "type": [
                                  "object",
                                  "null"
                                ],
                                "properties": {
                                  "training": {
                                    "type": "integer"
                                  },
                                  "search": {
                                    "type": "integer"
                                  },
                                  "browsing": {
                                    "type": "integer"
                                  }
                                },
                                "required": [
                                  "training",
                                  "search",
                                  "browsing"
                                ],
                                "additionalProperties": true
                              },
                              "referrals": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "ga4Referrals": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              }
                            },
                            "required": [
                              "day",
                              "crawlPulled",
                              "crawlRows",
                              "requests",
                              "byPurpose",
                              "referrals"
                            ],
                            "additionalProperties": true
                          },
                          "description": "Exactly 30, oldest first."
                        },
                        "bots": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "botName": {
                                "type": "string"
                              },
                              "detector": {
                                "type": "string"
                              },
                              "requests": {
                                "type": "integer"
                              },
                              "blockedRequests": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "daysSeen": {
                                "type": "integer"
                              },
                              "sampleRate": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "purpose": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "enum": [
                                  "training",
                                  "search",
                                  "browsing",
                                  null
                                ]
                              }
                            },
                            "required": [
                              "botName",
                              "detector",
                              "requests",
                              "daysSeen"
                            ],
                            "additionalProperties": true
                          },
                          "description": "At most 50."
                        },
                        "pages": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "path": {
                                "type": "string"
                              },
                              "requests": {
                                "type": "integer"
                              },
                              "byCrawler": {
                                "type": "array",
                                "items": {
                                  "type": "integer"
                                },
                                "description": "Requests per crawler, in `pageColumns` order."
                              },
                              "other": {
                                "type": "integer",
                                "description": "Requests from crawlers outside `pageColumns`."
                              },
                              "daysSeen": {
                                "type": "integer"
                              }
                            },
                            "required": [
                              "path",
                              "requests",
                              "byCrawler",
                              "other",
                              "daysSeen"
                            ],
                            "additionalProperties": true
                          },
                          "description": "At most 25."
                        },
                        "pageColumns": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "botName": {
                                "type": "string"
                              },
                              "live": {
                                "type": "boolean",
                                "description": "A user-triggered fetch rather than a crawl."
                              }
                            },
                            "required": [
                              "botName",
                              "live"
                            ],
                            "additionalProperties": true
                          },
                          "description": "At most 6."
                        },
                        "referralSources": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "provider": {
                                "type": "string"
                              },
                              "source": {
                                "type": "string"
                              },
                              "units": {
                                "type": "integer"
                              },
                              "unit": {
                                "type": "string"
                              },
                              "daysSeen": {
                                "type": "integer"
                              }
                            },
                            "required": [
                              "provider",
                              "source",
                              "units",
                              "unit",
                              "daysSeen"
                            ],
                            "additionalProperties": true
                          },
                          "description": "At most 10."
                        },
                        "liveDemand": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "liveRequests": {
                              "type": "integer"
                            },
                            "requests": {
                              "type": "integer"
                            },
                            "daysMeasured": {
                              "type": "integer"
                            },
                            "pages": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "path": {
                                    "type": "string"
                                  },
                                  "requests": {
                                    "type": "integer"
                                  },
                                  "liveRequests": {
                                    "type": "integer"
                                  }
                                },
                                "required": [
                                  "path",
                                  "requests",
                                  "liveRequests"
                                ],
                                "additionalProperties": true
                              },
                              "description": "At most 5."
                            }
                          },
                          "required": [
                            "liveRequests",
                            "requests",
                            "daysMeasured",
                            "pages"
                          ],
                          "additionalProperties": true,
                          "description": "User-triggered fetches — an AI surface reading a page to answer someone now."
                        }
                      },
                      "required": [
                        "days",
                        "bots",
                        "pages",
                        "pageColumns",
                        "referralSources",
                        "daysCovered"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "connectionStatus": null,
                    "connectionUpdatedAt": null,
                    "zoneTag": null,
                    "referralUnit": null,
                    "lastCrawlPullAt": null,
                    "daysCovered": 0,
                    "lastReferralPull": null,
                    "days": [],
                    "bots": [],
                    "pages": [],
                    "pageColumns": [],
                    "referralSources": [],
                    "liveDemand": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/crawl": {
      "post": {
        "operationId": "triggerAuditCrawl",
        "summary": "Re-crawl the brand's site",
        "description": "Queues a crawl of the audit's site. `mode` defaults to `force_fresh`, which always crawls; `reuse_if_fresh` keeps a completed crawl under 7 days old; `skip` keeps whatever crawl exists. **This starts paid work.**",
        "tags": [
          "traffic"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrawlTriggerRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The crawl is queued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "message"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "A crawl ran in the last 30 minutes (`error.details.reason` is `crawl_too_recent`), or one is already queued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "authored"
      }
    },
    "/eeat": {
      "post": {
        "operationId": "startEeatAnalysis",
        "summary": "Score a page",
        "description": "Starts scoring `url` for the audit `auditId` and answers **202**; poll `GET /eeat/{id}` until it is COMPLETED or FAILED. A completed analysis of the same page under 7 days old is returned as-is (**200**, `reused: true`) unless you pass `force=true`. **This starts paid work.**",
        "tags": [
          "eeat"
        ],
        "parameters": [
          {
            "name": "force",
            "in": "query",
            "required": false,
            "description": "Re-run even when a completed analysis under 7 days old exists.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EeatStartRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A recent analysis, reused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "const": "COMPLETED"
                        },
                        "reused": {
                          "type": "boolean",
                          "const": true
                        }
                      },
                      "required": [
                        "id",
                        "status",
                        "reused"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "202": {
            "description": "Started.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "const": "RUNNING"
                        }
                      },
                      "required": [
                        "id",
                        "status"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The page is already being scored.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "authored"
      }
    },
    "/eeat/{id}": {
      "get": {
        "operationId": "getEeatAnalysis",
        "summary": "Read a page score",
        "description": "One analysis with its scores. Each pillar is 0–10 and `overall` is their mean. `scores` and `assessment` are `null` until it completes.",
        "tags": [
          "eeat"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The analysis id, a UUID.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The analysis.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "crawledPageId": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "PENDING",
                            "RUNNING",
                            "COMPLETED",
                            "FAILED"
                          ]
                        },
                        "error": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "scores": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "experience": {
                              "type": "number"
                            },
                            "expertise": {
                              "type": "number"
                            },
                            "authoritativeness": {
                              "type": "number"
                            },
                            "trustworthiness": {
                              "type": "number"
                            },
                            "overall": {
                              "type": "number"
                            }
                          },
                          "required": [
                            "experience",
                            "expertise",
                            "authoritativeness",
                            "trustworthiness",
                            "overall"
                          ],
                          "additionalProperties": true
                        },
                        "assessment": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "additionalProperties": true,
                          "description": "The written assessment behind the scores."
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "completedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "id",
                        "url",
                        "crawledPageId",
                        "status",
                        "error",
                        "scores",
                        "assessment",
                        "createdAt",
                        "completedAt"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "00000000-0000-4000-8000-00000000e201",
                    "url": "https://example.com",
                    "crawledPageId": null,
                    "status": "COMPLETED",
                    "error": null,
                    "scores": {
                      "experience": 7,
                      "expertise": 6,
                      "authoritativeness": 5,
                      "trustworthiness": 8,
                      "overall": 6.5
                    },
                    "assessment": {
                      "summary": "Clear authorship and contact details."
                    },
                    "createdAt": "2026-10-26T19:53:04.867Z",
                    "completedAt": "2026-10-26T19:53:04.867Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/action-items/status": {
      "get": {
        "operationId": "listActionItemStatuses",
        "summary": "List action item statuses",
        "description": "Every item the team moved off `SUGGESTED`. An item not listed is `SUGGESTED`.",
        "tags": [
          "actions"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The statuses.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "statuses": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "itemKey": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "TODO",
                                  "DONE",
                                  "ARCHIVED"
                                ]
                              },
                              "doneAt": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "format": "date-time",
                                "description": "When it was marked `DONE`."
                              },
                              "doneTitle": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Its title when it was marked `DONE`."
                              },
                              "result": {
                                "type": [
                                  "object",
                                  "null"
                                ],
                                "properties": {
                                  "state": {
                                    "type": "string",
                                    "enum": [
                                      "untracked",
                                      "measuring",
                                      "no-run",
                                      "settled"
                                    ]
                                  },
                                  "measurableFrom": {
                                    "type": "string",
                                    "format": "date-time",
                                    "description": "Only while `measuring`: the first run that can show the effect."
                                  },
                                  "outcome": {
                                    "type": "object",
                                    "additionalProperties": true,
                                    "description": "Only when `settled`: the before-and-after reading."
                                  }
                                },
                                "required": [
                                  "state"
                                ],
                                "additionalProperties": true,
                                "description": "What marking it done changed. `null` unless `DONE`."
                              }
                            },
                            "required": [
                              "itemKey",
                              "status",
                              "doneAt",
                              "doneTitle",
                              "result"
                            ],
                            "additionalProperties": true
                          }
                        }
                      },
                      "required": [
                        "statuses"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "statuses": [
                      {
                        "itemKey": "technical:add-faq-schema",
                        "status": "DONE",
                        "doneAt": "2026-10-26T19:53:05.451Z",
                        "doneTitle": "Add FAQ schema to the pricing page",
                        "result": {
                          "state": "measuring",
                          "measurableFrom": "2026-11-02T19:53:05.451Z"
                        }
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "patch": {
        "operationId": "setActionItemStatus",
        "summary": "Set an action item's status",
        "description": "Moves one item to `TODO`, `DONE` or `ARCHIVED`, or back to `SUGGESTED`, which clears it. `title` is kept only on the move to `DONE`, so the item still lists after the report rewords it.",
        "tags": [
          "actions"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ActionItemStatusRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The status as recorded.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "itemKey": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "SUGGESTED",
                            "TODO",
                            "DONE",
                            "ARCHIVED"
                          ]
                        }
                      },
                      "required": [
                        "itemKey",
                        "status"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "itemKey": "technical:add-faq-schema",
                    "status": "DONE"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/action-items/counts": {
      "get": {
        "operationId": "getActionItemCounts",
        "summary": "Count suggested action items",
        "description": "How many items are still suggested, by type. `counts` is `null` until a run has finished.",
        "tags": [
          "actions"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The counts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "counts": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "total": {
                              "type": "integer"
                            },
                            "offPage": {
                              "type": "integer"
                            },
                            "onPage": {
                              "type": "integer"
                            },
                            "technical": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "total",
                            "offPage",
                            "onPage",
                            "technical"
                          ],
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "counts"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "counts": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/action-items/priority": {
      "get": {
        "operationId": "getPriorityActionItems",
        "summary": "Get the priority actions",
        "description": "The few suggested items worth doing first, ranked, with the technical quick wins and two totals. `priority` is `null` until a run has finished.",
        "tags": [
          "actions"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The priority actions.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "priority": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "items": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string"
                                  },
                                  "title": {
                                    "type": "string"
                                  },
                                  "domain": {
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "type": {
                                    "type": "string",
                                    "enum": [
                                      "on-page",
                                      "off-page",
                                      "technical"
                                    ]
                                  },
                                  "impact": {
                                    "type": "string",
                                    "enum": [
                                      "low",
                                      "medium",
                                      "high"
                                    ]
                                  },
                                  "promptCount": {
                                    "type": "integer"
                                  },
                                  "promptCountCapped": {
                                    "type": "boolean",
                                    "description": "The count is a floor — show it as \"5+\"."
                                  },
                                  "rivalCited": {
                                    "type": "boolean"
                                  },
                                  "openTerritory": {
                                    "type": "boolean"
                                  },
                                  "score": {
                                    "type": "number"
                                  },
                                  "related": {
                                    "type": "integer",
                                    "description": "Other suggested items folded into this one (same domain)."
                                  },
                                  "hook": {
                                    "type": [
                                      "object",
                                      "null"
                                    ],
                                    "additionalProperties": true,
                                    "description": "Why it ranks: `kind` is `cited`, `roundup`, `open_territory` or `low_hanging_fruit`."
                                  }
                                },
                                "required": [
                                  "key",
                                  "title",
                                  "type",
                                  "impact",
                                  "score"
                                ],
                                "additionalProperties": true
                              },
                              "description": "At most 5, best first."
                            },
                            "quickWins": {
                              "type": "object",
                              "properties": {
                                "total": {
                                  "type": "integer"
                                },
                                "items": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "key": {
                                        "type": "string"
                                      },
                                      "title": {
                                        "type": "string"
                                      }
                                    },
                                    "required": [
                                      "key",
                                      "title"
                                    ],
                                    "additionalProperties": true
                                  },
                                  "description": "At most 10."
                                }
                              },
                              "required": [
                                "total",
                                "items"
                              ],
                              "additionalProperties": true
                            },
                            "highImpact": {
                              "type": "integer",
                              "description": "Suggested items of high impact."
                            },
                            "totalSuggested": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "items",
                            "quickWins",
                            "highImpact",
                            "totalSuggested"
                          ],
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "priority"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "priority": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/action-items/custom": {
      "get": {
        "operationId": "listUserActionItems",
        "summary": "List added action items",
        "description": "Items the team added to the list, newest first. At most 200.",
        "tags": [
          "actions"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The items.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/UserActionItem"
                          }
                        }
                      },
                      "required": [
                        "items"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "items": [
                      {
                        "itemKey": "offpage:pitch-rival-com-roundup",
                        "title": "Pitch the widget roundup on rival.com",
                        "subtitle": null,
                        "type": "off-page",
                        "impact": "high"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "post": {
        "operationId": "addUserActionItem",
        "summary": "Add an action item",
        "description": "Adds an item to the list — a recommendation from the report, say — as `TODO`. Adding one with the key of an existing item replaces its content and keeps its status.",
        "tags": [
          "actions"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserActionItemRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The item as stored.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "item": {
                          "$ref": "#/components/schemas/UserActionItem"
                        }
                      },
                      "required": [
                        "item"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "item": {
                      "itemKey": "offpage:pitch-rival-com-roundup",
                      "title": "Pitch the widget roundup on rival.com",
                      "subtitle": null,
                      "type": "off-page",
                      "impact": "high"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "The audit already has 200 added items.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/action-items/custom/{itemKey}": {
      "delete": {
        "operationId": "removeUserActionItem",
        "summary": "Remove an added action item",
        "description": "Removes an item the team added. Removing one that does not exist succeeds.",
        "tags": [
          "actions"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "itemKey",
            "in": "path",
            "required": true,
            "description": "The item's key.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Removed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "itemKey": {
                          "type": "string"
                        },
                        "removed": {
                          "type": "boolean",
                          "const": true
                        }
                      },
                      "required": [
                        "itemKey",
                        "removed"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "itemKey": "offpage:pitch-rival-com-roundup",
                    "removed": true
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/action-items/links": {
      "get": {
        "operationId": "listActionItemLinks",
        "summary": "List action item links",
        "description": "The URLs the team attached to show work shipped, each with its newest check: whether the page is live in the crawl, cited by AI answers, or ranking. At most 500.",
        "tags": [
          "actions"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The links.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "links": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ActionItemLink"
                          }
                        }
                      },
                      "required": [
                        "links"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "links": [
                      {
                        "id": "d2a2ec00-64bb-4539-b6fe-59bbe4586a53",
                        "itemKey": "technical:add-faq-schema",
                        "url": "https://example.com/faq",
                        "label": "FAQ page",
                        "firstVerifiedAt": null,
                        "createdAt": "2026-10-26T19:53:04.869Z",
                        "outcome": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "post": {
        "operationId": "addActionItemLink",
        "summary": "Attach a link to an action item",
        "description": "Attaches an http(s) URL to an item and checks it against the newest snapshot straight away. Beket never fetches the URL; the check reads the run's data. `outcome` is `null` when there is no snapshot yet or the check failed.",
        "tags": [
          "actions"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ActionItemLinkRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The link.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "link": {
                          "$ref": "#/components/schemas/ActionItemLink"
                        }
                      },
                      "required": [
                        "link"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "link": {
                      "id": "35e17430-c4ad-4a24-90f8-aa488cb2d915",
                      "itemKey": "technical:add-faq-schema",
                      "url": "https://example.com/pricing",
                      "label": "Pricing page",
                      "firstVerifiedAt": null,
                      "createdAt": "2026-10-26T19:53:05.505Z",
                      "outcome": {
                        "crawlVisible": null,
                        "crawlDetail": "not in this crawl yet",
                        "crawlAgeDays": null,
                        "cited": false,
                        "domainCited": null,
                        "ranking": false,
                        "position": null,
                        "checkedAt": "2026-10-26T19:53:05.512Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "The item already has 5 links, or the audit 500.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/action-items/links/{linkId}": {
      "delete": {
        "operationId": "removeActionItemLink",
        "summary": "Detach a link",
        "description": "Removes a link. Removing one that does not exist succeeds.",
        "tags": [
          "actions"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "linkId",
            "in": "path",
            "required": true,
            "description": "The link's id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Removed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "linkId": {
                          "type": "string"
                        },
                        "removed": {
                          "type": "boolean",
                          "const": true
                        }
                      },
                      "required": [
                        "linkId",
                        "removed"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "linkId": "35e17430-c4ad-4a24-90f8-aa488cb2d915",
                    "removed": true
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/action-items/quotes": {
      "get": {
        "operationId": "listActionItemQuotes",
        "summary": "List quotes",
        "description": "Every quote requested on this audit, with Beket's replies.",
        "tags": [
          "actions"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The quotes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "quotes": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ActionItemQuote"
                          }
                        }
                      },
                      "required": [
                        "quotes"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "quotes": [
                      {
                        "id": "ebb4822e-e3a9-4270-8ec9-df946825336d",
                        "itemKey": "offpage:pitch-rival-com-roundup",
                        "status": "QUOTED",
                        "itemTitle": "Get listed in the rival.com widget roundup",
                        "itemSummary": "rival.com is cited for 3 prompts where Example Co is absent.",
                        "note": null,
                        "replies": [
                          {
                            "sentAt": "2026-10-20T12:00:00.000Z",
                            "sentBy": "clrecorderuser00000000001",
                            "message": "We can place this within two weeks.",
                            "outcome": "QUOTED",
                            "priceCents": 45000
                          }
                        ],
                        "createdAt": "2026-10-26T19:53:04.872Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/action-items/quote": {
      "post": {
        "operationId": "requestActionItemQuote",
        "summary": "Request a quote",
        "description": "Asks the Beket team to price one off-site item — an engagement or citation-gap item. **This contacts the Beket team**, who reply by email and in the quote's `replies`. Answers **201** for a new request and **200** with the existing one when the item was already requested. Needs a user's API key: a request is answered to a person.",
        "tags": [
          "actions"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ActionItemQuoteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Already requested.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/ActionItemQuoteResult"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "201": {
            "description": "Requested.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/ActionItemQuoteResult"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "The item is not an off-site item, so it cannot be quoted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/indexnow": {
      "get": {
        "operationId": "getIndexNowKey",
        "summary": "Get the IndexNow key",
        "description": "The key the site hosts so search engines accept its IndexNow pings, and whether Beket has found it live.",
        "tags": [
          "actions"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "key": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "`null` until a key is issued."
                        },
                        "keyLocation": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The URL the key file must answer at."
                        },
                        "host": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "`null` until the site is crawled."
                        },
                        "verifiedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "file": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The path to host the key file at."
                        }
                      },
                      "required": [
                        "key",
                        "keyLocation",
                        "host",
                        "verifiedAt",
                        "file"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "key": null,
                    "keyLocation": null,
                    "host": "example.com",
                    "verifiedAt": null,
                    "file": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/indexnow/verify": {
      "post": {
        "operationId": "verifyIndexNowKey",
        "summary": "Verify the IndexNow key",
        "description": "Issues a key if there is none, then fetches the key file from the site and records `verifiedAt` when it matches. `verified: false` means the file is not live yet — host `contents` at `file`.",
        "tags": [
          "actions"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The check.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "verified": {
                          "type": "boolean"
                        },
                        "key": {
                          "type": "string"
                        },
                        "keyLocation": {
                          "type": "string",
                          "description": "The URL the key file must answer at."
                        },
                        "host": {
                          "type": "string"
                        },
                        "verifiedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time",
                          "description": "Set by this check when it matched, or by an earlier one."
                        },
                        "file": {
                          "type": "string",
                          "description": "The path to host the key file at."
                        },
                        "contents": {
                          "type": "string",
                          "description": "The exact contents the file must hold."
                        }
                      },
                      "required": [
                        "verified",
                        "key",
                        "keyLocation",
                        "host",
                        "verifiedAt",
                        "file",
                        "contents"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "The site has not been crawled, so there is no host to check.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/content/briefs": {
      "get": {
        "operationId": "listAuditContentBriefs",
        "summary": "List content briefs",
        "description": "The audit's newest 50 briefs, newest first, without their bodies — read one brief for its `payload`.",
        "tags": [
          "content"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The briefs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ContentBriefSummary"
                      }
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "id": "clrecorderbrief0000000001",
                      "auditId": "clrecorderaudit0000000001",
                      "contentPieceIndex": 0,
                      "sourcePiece": {
                        "title": "Widget software buyer's guide",
                        "format": "guide"
                      },
                      "version": 1,
                      "status": "READY",
                      "createdAt": "2026-10-26T19:53:04.865Z",
                      "updatedAt": "2026-10-26T19:53:04.865Z"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      },
      "post": {
        "operationId": "createAuditContentBrief",
        "summary": "Generate a content brief",
        "description": "Starts generating a brief for one piece of the audit's content roadmap (`contentPieceIndex` counts from 0) and answers **202**; poll the brief until it is READY or FAILED. Counts against the plan's monthly content allowance; at the cap it answers **429** with `error.details.reason` and `nextResetAt`. **This starts paid work.**",
        "tags": [
          "content"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContentBriefCreateRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Started.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "briefId": {
                          "type": "string"
                        },
                        "version": {
                          "type": "integer"
                        },
                        "status": {
                          "type": "string",
                          "const": "PENDING"
                        }
                      },
                      "required": [
                        "briefId",
                        "version",
                        "status"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "authored"
      }
    },
    "/audits/{auditId}/content/briefs/{briefId}": {
      "get": {
        "operationId": "getAuditContentBrief",
        "summary": "Read a content brief",
        "description": "One brief with its generated `payload` and your `editedPayload`.",
        "tags": [
          "content"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "briefId",
            "in": "path",
            "required": true,
            "description": "The brief's id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The brief.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/ContentBrief"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "clrecorderbrief0000000001",
                    "auditId": "clrecorderaudit0000000001",
                    "contentPieceIndex": 0,
                    "sourcePiece": {
                      "title": "Widget software buyer's guide",
                      "format": "guide"
                    },
                    "version": 1,
                    "status": "READY",
                    "createdAt": "2026-10-26T19:53:04.865Z",
                    "updatedAt": "2026-10-26T19:53:04.865Z",
                    "payload": {
                      "outline": [
                        {
                          "level": 2,
                          "heading": "How to choose widget software",
                          "keyPoints": [
                            "Team size",
                            "Integrations"
                          ]
                        }
                      ],
                      "introAngle": "Most teams outgrow their first widget tool within a year.",
                      "citationPlan": "Link two third-party reviews.",
                      "targetQueries": [
                        {
                          "angle": "BRAND_DISCOVERY",
                          "queryText": "what is the best widget software",
                          "suggestedContentType": "guide",
                          "expectedAiResponseFormat": "ranked list"
                        }
                      ],
                      "sourceStrategy": [
                        {
                          "approach": "Cite independent benchmarks.",
                          "sourceGapDomain": "rival.com"
                        }
                      ],
                      "wordCountTarget": 1800,
                      "answerEngineFormat": "A ranked list with a one-line verdict per tool.",
                      "schemaRecommendations": [
                        "FAQPage"
                      ],
                      "topicOwnershipContext": "Example Co is absent from 3 of 4 answers on this topic.",
                      "competitorQuotesToBeat": [
                        {
                          "quote": "Rival is the simplest widget tool.",
                          "competitorName": "Rival"
                        }
                      ],
                      "suggestedInternalLinks": [
                        {
                          "url": "https://example.com/pricing",
                          "title": "Pricing",
                          "anchorRationale": "Buyers compare cost."
                        }
                      ]
                    },
                    "editedPayload": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/content/briefs/{briefId}/draft": {
      "post": {
        "operationId": "createAuditContentDraft",
        "summary": "Write a draft from a brief",
        "description": "Starts writing a long-form draft from a READY brief (your edit wins) and answers **202**; poll the draft until it is READY or FAILED. Counts against the plan's monthly content allowance; at the cap it answers **429** with `error.details.reason` and `nextResetAt`. **This starts paid work.**",
        "tags": [
          "content"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "briefId",
            "in": "path",
            "required": true,
            "description": "The brief's id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Started.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "draftId": {
                          "type": "string"
                        },
                        "version": {
                          "type": "integer"
                        },
                        "status": {
                          "type": "string",
                          "const": "PENDING"
                        }
                      },
                      "required": [
                        "draftId",
                        "version",
                        "status"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The brief is not READY yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "authored"
      }
    },
    "/audits/{auditId}/content/briefs/{briefId}/drafts": {
      "get": {
        "operationId": "listAuditContentDrafts",
        "summary": "List a brief's drafts",
        "description": "Every draft written from the brief, newest first. `content` is `null` here; read one draft for it.",
        "tags": [
          "content"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "briefId",
            "in": "path",
            "required": true,
            "description": "The brief's id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The drafts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ContentDraft"
                      }
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "id": "clrecorderdraft0000000001",
                      "briefId": "clrecorderbrief0000000001",
                      "auditId": "clrecorderaudit0000000001",
                      "version": 1,
                      "status": "FAILED",
                      "content": null,
                      "contentMeta": null,
                      "violations": [],
                      "violationsTruncated": false,
                      "createdAt": "2026-10-26T19:53:04.866Z",
                      "updatedAt": "2026-10-26T19:53:04.866Z"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/content/drafts/{draftId}": {
      "get": {
        "operationId": "getAuditContentDraft",
        "summary": "Read a draft",
        "description": "One draft with its Markdown `content`, which is `null` until the draft is READY.",
        "tags": [
          "content"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "draftId",
            "in": "path",
            "required": true,
            "description": "The draft's id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The draft.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/ContentDraft"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "clrecorderdraft0000000001",
                    "briefId": "clrecorderbrief0000000001",
                    "auditId": "clrecorderaudit0000000001",
                    "version": 1,
                    "status": "FAILED",
                    "content": null,
                    "contentMeta": null,
                    "violations": [],
                    "violationsTruncated": false,
                    "createdAt": "2026-10-26T19:53:04.866Z",
                    "updatedAt": "2026-10-26T19:53:04.866Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/audits/{auditId}/content/drafts/{draftId}/regenerate": {
      "post": {
        "operationId": "regenerateAuditContentDraft",
        "summary": "Rewrite a draft",
        "description": "Rewrites a READY or FAILED draft in place from its brief and answers **202**; poll the draft again. Counts against the plan's monthly content allowance; at the cap it answers **429** with `error.details.reason` and `nextResetAt`. **This starts paid work.**",
        "tags": [
          "content"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "draftId",
            "in": "path",
            "required": true,
            "description": "The draft's id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Started.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "draftId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "const": "PENDING"
                        }
                      },
                      "required": [
                        "draftId",
                        "status"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The draft is already being written.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "authored"
      }
    },
    "/audits/{auditId}/signals": {
      "get": {
        "operationId": "listAuditSignals",
        "summary": "List an audit's signals",
        "description": "Open and dismissed signals (at most 100), then signals resolved in the last 30 days (at most 50). `truncated` says whether either list hit its cap.",
        "tags": [
          "signals"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          }
        ],
        "responses": {
          "200": {
            "description": "The signals.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "signals": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "new_competitor",
                                  "entity_disappeared",
                                  "new_citation_source",
                                  "metric_delta",
                                  "edge_blocked_crawler"
                                ]
                              },
                              "state": {
                                "type": "string",
                                "enum": [
                                  "open",
                                  "dismissed",
                                  "resolved"
                                ]
                              },
                              "dedupKey": {
                                "type": "string",
                                "description": "Identifies the condition; a recurrence of a resolved one is a new signal."
                              },
                              "payload": {
                                "type": "object",
                                "additionalProperties": true,
                                "description": "Kind-specific detail (the competitor, the source, the metric and its delta)."
                              },
                              "firstSeenAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "lastSeenAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "resolvedAt": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "format": "date-time"
                              },
                              "dismissedAt": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "format": "date-time"
                              },
                              "firstSeenSnapshotId": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "lastSeenSnapshotId": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            },
                            "required": [
                              "id",
                              "kind",
                              "state",
                              "dedupKey",
                              "payload",
                              "firstSeenAt",
                              "lastSeenAt",
                              "resolvedAt",
                              "dismissedAt"
                            ],
                            "additionalProperties": true
                          }
                        },
                        "truncated": {
                          "type": "object",
                          "properties": {
                            "live": {
                              "type": "boolean"
                            },
                            "resolved": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "live",
                            "resolved"
                          ],
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "signals",
                        "truncated"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "signals": [
                      {
                        "id": "clrecordersignal000000001",
                        "kind": "new_competitor",
                        "state": "open",
                        "dedupKey": "new_competitor:rival",
                        "payload": {
                          "subject": "Rival"
                        },
                        "firstSeenAt": "2026-10-25T19:53:04.852Z",
                        "lastSeenAt": "2026-10-25T19:53:04.852Z",
                        "resolvedAt": null,
                        "dismissedAt": null,
                        "firstSeenSnapshotId": "00000000-0000-4000-8000-00000000e102",
                        "lastSeenSnapshotId": "00000000-0000-4000-8000-00000000e102"
                      }
                    ],
                    "truncated": {
                      "live": false,
                      "resolved": false
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/zapier/me": {
      "get": {
        "operationId": "getZapierMe",
        "summary": "Identify the key's organization",
        "description": "The organization this key belongs to, and the key's name. Cheap and side-effect free: use it to test a connection.",
        "tags": [
          "zapier"
        ],
        "responses": {
          "200": {
            "description": "The key's organization.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "orgId": {
                          "type": "string"
                        },
                        "orgName": {
                          "type": "string"
                        },
                        "keyName": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "orgId",
                        "orgName",
                        "keyName"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": {
                    "orgId": "00000000-0000-4000-8000-00000000e001",
                    "orgName": "Recorder Fixture",
                    "keyName": "Recorder"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/zapier/audits": {
      "get": {
        "operationId": "listZapierAudits",
        "summary": "List audits for a picker",
        "description": "Your organization's live audits as id/label pairs, for a dropdown.",
        "tags": [
          "zapier"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Rows to return, newest first. Defaults to 100; a value above 100 is a 400.",
            "schema": {
              "default": 100,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The audits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "subject": {
                            "type": "string"
                          },
                          "mode": {
                            "type": "string",
                            "enum": [
                              "brand",
                              "market"
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "subject",
                          "mode"
                        ],
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "id": "clrecorderaudit0000000001",
                      "name": "Example Co",
                      "subject": "example.com",
                      "mode": "brand"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/zapier/runs": {
      "get": {
        "operationId": "listZapierRuns",
        "summary": "List recently completed runs",
        "description": "Completed runs with their headline numbers and a report link. Only the last 7 days are returned, newest first — poll it and dedupe on `id`. An `auditId` that is not a live audit of your organization is a 404, never an empty list, so a poll cannot silently watch nothing. Responses are `Cache-Control: private, no-store`.",
        "tags": [
          "zapier"
        ],
        "parameters": [
          {
            "name": "auditId",
            "in": "query",
            "required": false,
            "description": "Only this audit. A malformed id is a 400; an id that is not a live audit of your organization is a 404.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Rows to return, newest first. Defaults to 50; a value above 100 is a 400.",
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The runs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "The snapshot id — the event's dedupe key."
                          },
                          "auditId": {
                            "type": "string"
                          },
                          "auditName": {
                            "type": "string"
                          },
                          "subject": {
                            "type": "string",
                            "description": "The domain for a brand audit, the topic for a market audit."
                          },
                          "runType": {
                            "type": "string",
                            "enum": [
                              "full",
                              "short"
                            ]
                          },
                          "completedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "aiVisibility": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "shareOfVoice": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "topCompetitors": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "maxItems": 3,
                            "description": "Competitor names, highest share first."
                          },
                          "reportUrl": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "auditId",
                          "auditName",
                          "subject",
                          "runType",
                          "completedAt",
                          "aiVisibility",
                          "shareOfVoice",
                          "topCompetitors",
                          "reportUrl"
                        ],
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "id": "00000000-0000-4000-8000-00000000e102",
                      "auditId": "clrecorderaudit0000000001",
                      "auditName": "Example Co",
                      "subject": "example.com",
                      "runType": "full",
                      "completedAt": "2026-10-25T19:53:04.851Z",
                      "aiVisibility": 0.62,
                      "shareOfVoice": 0.6,
                      "topCompetitors": [
                        "Rival"
                      ],
                      "reportUrl": "https://app.beket.ai/audit/clrecorderaudit0000000001/report"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/zapier/signals": {
      "get": {
        "operationId": "listZapierSignals",
        "summary": "List recent signals",
        "description": "Signals first seen recently — a new competitor, a lost citation, a metric swing — flattened to one row each. Dismissed signals are left out. Only the last 7 days are returned, newest first — poll it and dedupe on `id`. An `auditId` that is not a live audit of your organization is a 404, never an empty list, so a poll cannot silently watch nothing. Responses are `Cache-Control: private, no-store`.",
        "tags": [
          "zapier"
        ],
        "parameters": [
          {
            "name": "auditId",
            "in": "query",
            "required": false,
            "description": "Only this audit. A malformed id is a 400; an id that is not a live audit of your organization is a 404.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "Only signals of this kind.",
            "schema": {
              "type": "string",
              "enum": [
                "new_competitor",
                "entity_disappeared",
                "new_citation_source",
                "metric_delta",
                "edge_blocked_crawler"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Rows to return, newest first. Defaults to 50; a value above 100 is a 400.",
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The signals.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "auditId": {
                            "type": "string"
                          },
                          "auditName": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "new_competitor",
                              "entity_disappeared",
                              "new_citation_source",
                              "metric_delta",
                              "edge_blocked_crawler"
                            ]
                          },
                          "kindLabel": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string",
                            "description": "The same words the report shows for this signal."
                          },
                          "firstSeenAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "open",
                              "resolved"
                            ]
                          },
                          "reportUrl": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "auditId",
                          "auditName",
                          "kind",
                          "kindLabel",
                          "title",
                          "firstSeenAt",
                          "state",
                          "reportUrl"
                        ],
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "id": "clrecordersignal000000001",
                      "auditId": "clrecorderaudit0000000001",
                      "auditName": "Example Co",
                      "kind": "new_competitor",
                      "kindLabel": "New competitor",
                      "title": "Rival started appearing in AI answers",
                      "firstSeenAt": "2026-10-25T19:53:04.852Z",
                      "state": "open",
                      "reportUrl": "https://app.beket.ai/audit/clrecorderaudit0000000001/report?section=competitors"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationFailed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "recorded"
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApiDocument",
        "summary": "Get this OpenAPI document",
        "description": "The OpenAPI 3.1 document describing every documented endpoint — feed it to a client generator, an agent, or your editor. **Public: no credentials required**, so a developer or an agent can read what the API offers before holding a key.\n\nUnlike every other endpoint, this one returns the document as the raw response body, NOT wrapped in the `{ success, data }` envelope — a wrapped document is unreadable to standard OpenAPI tooling. Served with an `ETag`; send `If-None-Match` and expect a 304 when nothing has changed.",
        "tags": [
          "meta"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "The OpenAPI document, unwrapped.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "304": {
            "description": "The document is unchanged since the `If-None-Match` value."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-example-source": "authored"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key created by an owner in Settings → Developer & AI → API keys, sent as `Authorization: Bearer bkt_…`. Scoped to one organization and capped at the editor role; read-only keys may only issue GET, HEAD and OPTIONS requests."
      }
    },
    "schemas": {
      "AuditCreateRequest": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "entityId": {
                "type": "string"
              },
              "subjectPath": {
                "not": {}
              },
              "notificationEmail": {
                "type": "string",
                "format": "email",
                "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
              }
            },
            "required": [
              "entityId"
            ]
          },
          {
            "type": "object",
            "properties": {
              "domain": {
                "type": "string",
                "minLength": 1
              },
              "subjectPath": {
                "type": "string",
                "minLength": 1
              },
              "reuse": {
                "type": "boolean"
              },
              "notificationEmail": {
                "type": "string",
                "format": "email",
                "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
              }
            },
            "required": [
              "domain"
            ]
          },
          {
            "type": "object",
            "properties": {
              "topic": {
                "type": "string",
                "minLength": 1
              },
              "subjectPath": {
                "not": {}
              },
              "notificationEmail": {
                "type": "string",
                "format": "email",
                "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
              }
            },
            "required": [
              "topic"
            ]
          },
          {
            "type": "object",
            "properties": {
              "profile": {
                "type": "object",
                "properties": {
                  "brandName": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "category": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "products": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "competitors": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "category"
                ],
                "additionalProperties": {}
              },
              "subjectPath": {
                "not": {}
              },
              "notificationEmail": {
                "type": "string",
                "format": "email",
                "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
              }
            },
            "required": [
              "profile"
            ]
          }
        ]
      },
      "AuditProfileUpdateRequest": {
        "type": "object",
        "properties": {
          "brandName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 8000
          },
          "brandAliases": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "primaryProduct": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 8000
              },
              {
                "type": "null"
              }
            ]
          },
          "offer": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 8000
              },
              {
                "type": "null"
              }
            ]
          },
          "description": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 8000
              },
              {
                "type": "null"
              }
            ]
          },
          "icp": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "differentiators": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "painPoints": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "vertical": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 500
              },
              {
                "type": "null"
              }
            ]
          },
          "categoryLabel": {
            "description": "What the business does, e.g. \"commercial cleaning\". A label that only ranks (\"best\", \"top\") is refused.",
            "anyOf": [
              {
                "type": "string",
                "maxLength": 8000
              },
              {
                "type": "null"
              }
            ]
          },
          "segment": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 500
              },
              {
                "type": "null"
              }
            ]
          },
          "marketScope": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "local",
                  "regional",
                  "national",
                  "online"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "city": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 8000
              },
              {
                "type": "null"
              }
            ]
          },
          "serviceRadius": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 8000
              },
              {
                "type": "null"
              }
            ]
          },
          "anchors": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "address": {
                    "default": "",
                    "type": "string"
                  },
                  "phone": {
                    "default": "",
                    "type": "string"
                  },
                  "gbp": {
                    "default": "",
                    "type": "string"
                  },
                  "profiles": {
                    "default": "",
                    "type": "string"
                  },
                  "socials": {
                    "default": [],
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "platform": {
                          "type": "string",
                          "enum": [
                            "linkedin",
                            "x",
                            "instagram",
                            "facebook",
                            "youtube",
                            "tiktok",
                            "github",
                            "crunchbase",
                            "yelp",
                            "other"
                          ]
                        },
                        "url": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "platform",
                        "url"
                      ]
                    }
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "verifiedClaims": {
            "maxItems": 200,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "text": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 2000
                },
                "verified": {
                  "default": false,
                  "type": "boolean"
                }
              },
              "required": [
                "text"
              ]
            }
          },
          "neutralDescription": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 8000
              },
              {
                "type": "null"
              }
            ]
          },
          "painPrompts": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "text": {
                  "type": "string",
                  "minLength": 1
                },
                "promptEN": {
                  "type": "string",
                  "minLength": 1
                },
                "promptFR": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "on": {
                  "default": true,
                  "type": "boolean"
                }
              },
              "required": [
                "text",
                "promptEN"
              ]
            }
          }
        },
        "required": [
          "brandName",
          "brandAliases",
          "icp",
          "differentiators",
          "painPoints"
        ]
      },
      "AuditConnectorsUpdateRequest": {
        "type": "object",
        "properties": {
          "connectorTypes": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "OPENAI",
                "OPENAI_GPT",
                "GOOGLE_AI_OVERVIEW",
                "GOOGLE_AI_MODE",
                "PERPLEXITY",
                "COPILOT",
                "CLAUDE",
                "GEMINI_APP",
                "CHATGPT_APP",
                "XAI_GROK"
              ]
            }
          }
        },
        "required": [
          "connectorTypes"
        ]
      },
      "AuditCompetitorsUpdateRequest": {
        "type": "object",
        "properties": {
          "competitors": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 120
                },
                "domain": {
                  "description": "The competitor's site, like `domain.com`. Blank or null when it has none; anything else that is not a plausible host is a 400.",
                  "anyOf": [
                    {
                      "type": "string",
                      "maxLength": 253
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "sizeTier": {
                  "type": "string",
                  "enum": [
                    "startup",
                    "smb",
                    "mid-market",
                    "enterprise",
                    "unknown"
                  ]
                },
                "classification": {
                  "type": "string",
                  "enum": [
                    "direct",
                    "indirect",
                    "not-competitor"
                  ]
                },
                "evidence": {
                  "anyOf": [
                    {
                      "type": "string",
                      "maxLength": 500
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "name"
              ]
            }
          }
        },
        "required": [
          "competitors"
        ]
      },
      "AuditTargetingUpdateRequest": {
        "type": "object",
        "properties": {
          "languages": {
            "maxItems": 10,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40,
              "pattern": "^\\p{L}[\\p{L} -]*$"
            }
          },
          "locations": {
            "default": [],
            "maxItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          }
        }
      },
      "AuditSchedulePatchRequest": {
        "type": "object",
        "properties": {
          "snapshotEnabled": {
            "type": "boolean"
          },
          "snapshotTimeZone": {
            "description": "The time zone whose night the daily snapshot runs in, as an IANA name (`Europe/Berlin`). `null` removes the override, so the organization's zone applies.",
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "description": "Send `snapshotEnabled`, `snapshotTimeZone`, or both; an empty body is a 400."
      },
      "PromptGenerateRequest": {
        "default": {},
        "type": "object",
        "properties": {
          "topicIds": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "languages": {
            "maxItems": 10,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40,
              "pattern": "^\\p{L}[\\p{L} -]*$"
            }
          }
        }
      },
      "PromptPreviewRequest": {
        "type": "object",
        "properties": {
          "profile": {
            "type": "object",
            "properties": {
              "brandName": {
                "type": "string",
                "maxLength": 8000
              },
              "brandAliases": {
                "maxItems": 50,
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "primaryProduct": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 8000
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "offer": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 8000
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 8000
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "icp": {
                "maxItems": 50,
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "differentiators": {
                "maxItems": 50,
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "painPoints": {
                "maxItems": 50,
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "vertical": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 500
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "categoryLabel": {
                "description": "What the business does, e.g. \"commercial cleaning\". A label that only ranks (\"best\", \"top\") is refused.",
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 8000
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "segment": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 500
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "marketScope": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "local",
                      "regional",
                      "national",
                      "online"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "city": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 8000
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "serviceRadius": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 8000
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "anchors": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "address": {
                        "default": "",
                        "type": "string"
                      },
                      "phone": {
                        "default": "",
                        "type": "string"
                      },
                      "gbp": {
                        "default": "",
                        "type": "string"
                      },
                      "profiles": {
                        "default": "",
                        "type": "string"
                      },
                      "socials": {
                        "default": [],
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "platform": {
                              "type": "string",
                              "enum": [
                                "linkedin",
                                "x",
                                "instagram",
                                "facebook",
                                "youtube",
                                "tiktok",
                                "github",
                                "crunchbase",
                                "yelp",
                                "other"
                              ]
                            },
                            "url": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "platform",
                            "url"
                          ]
                        }
                      }
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "verifiedClaims": {
                "maxItems": 200,
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "text": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 2000
                    },
                    "verified": {
                      "default": false,
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "text"
                  ]
                }
              },
              "neutralDescription": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 8000
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "painPrompts": {
                "maxItems": 50,
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "text": {
                      "type": "string",
                      "minLength": 1
                    },
                    "promptEN": {
                      "type": "string",
                      "minLength": 1
                    },
                    "promptFR": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "on": {
                      "default": true,
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "text",
                    "promptEN"
                  ]
                }
              }
            }
          },
          "competitors": {
            "default": [],
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 120
                },
                "domain": {
                  "description": "The competitor's site, like `domain.com`. Blank or null when it has none; anything else that is not a plausible host is a 400.",
                  "anyOf": [
                    {
                      "type": "string",
                      "maxLength": 253
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "sizeTier": {
                  "type": "string",
                  "enum": [
                    "startup",
                    "smb",
                    "mid-market",
                    "enterprise",
                    "unknown"
                  ]
                },
                "classification": {
                  "type": "string",
                  "enum": [
                    "direct",
                    "indirect",
                    "not-competitor"
                  ]
                },
                "evidence": {
                  "anyOf": [
                    {
                      "type": "string",
                      "maxLength": 500
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "name"
              ]
            }
          },
          "topicIds": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "languages": {
            "maxItems": 10,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40,
              "pattern": "^\\p{L}[\\p{L} -]*$"
            }
          }
        }
      },
      "PromptAddRequest": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "minLength": 3,
            "maxLength": 500
          },
          "selectedIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          }
        },
        "required": [
          "text"
        ]
      },
      "PromptBulkAddRequest": {
        "type": "object",
        "properties": {
          "texts": {
            "minItems": 1,
            "maxItems": 100,
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 1000
            }
          },
          "selectedIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "returnPrompts": {
            "default": true,
            "type": "boolean"
          }
        },
        "required": [
          "texts"
        ]
      },
      "PromptSelectionUpdateRequest": {
        "type": "object",
        "properties": {
          "selectedIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          }
        },
        "required": [
          "selectedIds"
        ]
      },
      "PromptActionRequest": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "select",
              "deselect",
              "remove",
              "restore"
            ]
          },
          "queryIds": {
            "minItems": 1,
            "maxItems": 500,
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Prompt ids. Repeats collapse; an id that is not a prompt of this audit is answered `not_found`."
          }
        },
        "required": [
          "action",
          "queryIds"
        ]
      },
      "PromptImportRequest": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "minLength": 1,
            "maxLength": 5242880
          },
          "dryRun": {
            "default": false,
            "type": "boolean"
          },
          "replaceSelection": {
            "default": false,
            "type": "boolean"
          }
        },
        "required": [
          "content"
        ]
      },
      "PromptEditRequest": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "minLength": 3,
            "maxLength": 500
          }
        },
        "required": [
          "text"
        ]
      },
      "PromptTypeUpdateRequest": {
        "type": "object",
        "properties": {
          "promptType": {
            "type": "string",
            "enum": [
              "UNBRANDED",
              "BRANDED",
              "RECALL"
            ]
          }
        },
        "required": [
          "promptType"
        ]
      },
      "PromptLanguageUpdateRequest": {
        "type": "object",
        "properties": {
          "language": {
            "description": "One language, as a name or an ISO 639-1 code (`French`, `FR`). Stored as the uppercase code; anything else is a 400.",
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          }
        },
        "required": [
          "language"
        ]
      },
      "PromptTopicAssignRequest": {
        "type": "object",
        "properties": {
          "queryIds": {
            "minItems": 1,
            "maxItems": 500,
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Prompt ids of this audit."
          },
          "topicId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "An id of this audit's topics, or `null` to file the prompts under none."
          }
        },
        "required": [
          "queryIds",
          "topicId"
        ]
      },
      "TopicLabelRequest": {
        "type": "object",
        "properties": {
          "label": {
            "description": "The topic's name: surrounding and repeated whitespace is collapsed, then it must be 1–80 characters.",
            "type": "string",
            "maxLength": 320
          }
        },
        "required": [
          "label"
        ]
      },
      "TopicMergeRequest": {
        "type": "object",
        "properties": {
          "intoTopicId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The topic that receives the prompts — an id of this audit's topics — or `null` to leave them in no topic."
          }
        },
        "required": [
          "intoTopicId"
        ]
      },
      "FirstPartyTermsImportRequest": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "minLength": 1,
            "description": "The Google Ads search-terms report, exported as CSV, as text."
          },
          "rewrite": {
            "type": "boolean",
            "description": "Also write each term as a question, in the background. The list shows `rewriting` until it lands."
          }
        },
        "required": [
          "content",
          "rewrite"
        ]
      },
      "FirstPartyTermsSelectRequest": {
        "type": "object",
        "properties": {
          "termIds": {
            "minItems": 1,
            "maxItems": 100,
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Term ids from the term list. A term that is not one of this audit's is a 404."
          }
        },
        "required": [
          "termIds"
        ]
      },
      "AuditStartRequest": {
        "type": "object",
        "properties": {
          "connectorTypes": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "OPENAI",
                "OPENAI_GPT",
                "GOOGLE_AI_OVERVIEW",
                "GOOGLE_AI_MODE",
                "PERPLEXITY",
                "COPILOT",
                "CLAUDE",
                "GEMINI_APP",
                "CHATGPT_APP",
                "XAI_GROK"
              ]
            }
          },
          "model": {
            "type": "string",
            "minLength": 1
          },
          "languages": {
            "maxItems": 10,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40,
              "pattern": "^\\p{L}[\\p{L} -]*$"
            }
          },
          "locations": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "angleIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "snapshotTimeZone": {
            "description": "An IANA time zone, e.g. \"America/Toronto\"; anything else is refused.",
            "type": "string"
          }
        },
        "required": [
          "connectorTypes"
        ]
      },
      "AuditRunRequest": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "minLength": 1
          },
          "angles": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "queriesPerAngle": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20
          },
          "refreshAnswers": {
            "type": "boolean"
          },
          "forceRecover": {
            "type": "boolean"
          },
          "connectorTypes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "enrichCompetitors": {
            "type": "boolean"
          },
          "crawlPolicy": {
            "type": "string",
            "enum": [
              "skip",
              "reuse_if_fresh",
              "force_fresh"
            ]
          },
          "crawlFreshnessMaxAgeDays": {
            "type": "integer",
            "minimum": 1,
            "maximum": 365
          },
          "createSnapshot": {
            "type": "boolean"
          },
          "snapshotLabel": {
            "type": "string"
          }
        }
      },
      "CrawlTriggerRequest": {
        "default": {},
        "type": "object",
        "properties": {
          "mode": {
            "default": "force_fresh",
            "type": "string",
            "enum": [
              "skip",
              "reuse_if_fresh",
              "force_fresh"
            ]
          }
        }
      },
      "SnapshotCreateRequest": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1
          },
          "baselineSnapshotId": {
            "description": "The id of an earlier snapshot of this audit (a UUID, or a legacy cuid) that a compare with `a` omitted measures this one against. Omit it for no baseline.",
            "type": "string"
          }
        }
      },
      "BrandFactCreateRequest": {
        "type": "object",
        "properties": {
          "factKey": {
            "type": "string",
            "enum": [
              "claim",
              "phone",
              "address",
              "hours",
              "primary_category",
              "service_area",
              "headquarters",
              "founded_year",
              "founder",
              "pricing_model",
              "price_range",
              "certification",
              "offering"
            ]
          },
          "value": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "sourceUrl": {
            "description": "Where the value is stated: an http(s) URL. Empty or `null` for none.",
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2048
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "factKey",
          "value"
        ],
        "additionalProperties": false
      },
      "BrandFactConfirmRequest": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "sourceUrl": {
            "description": "Where the value is stated: an http(s) URL. Empty or `null` for none.",
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2048
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "additionalProperties": false
      },
      "SourceTypeOverrideRequest": {
        "type": "object",
        "properties": {
          "target": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2048
          },
          "sourceType": {
            "type": "string",
            "enum": [
              "forum",
              "qa",
              "review_site",
              "directory",
              "video",
              "social",
              "news",
              "blog",
              "reference",
              "code",
              "vendor",
              "search_engine",
              "other"
            ]
          }
        },
        "required": [
          "target",
          "sourceType"
        ]
      },
      "CitationWatchRequest": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "minLength": 1,
            "maxLength": 253
          }
        },
        "required": [
          "domain"
        ]
      },
      "EeatStartRequest": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "auditId": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "url",
          "auditId"
        ]
      },
      "ActionItemStatusRequest": {
        "type": "object",
        "properties": {
          "itemKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512
          },
          "status": {
            "type": "string",
            "enum": [
              "SUGGESTED",
              "TODO",
              "DONE",
              "ARCHIVED"
            ]
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          }
        },
        "required": [
          "itemKey",
          "status"
        ]
      },
      "UserActionItemRequest": {
        "type": "object",
        "properties": {
          "itemKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "subtitle": {
            "type": "string",
            "maxLength": 500
          },
          "type": {
            "type": "string",
            "enum": [
              "on-page",
              "off-page",
              "technical"
            ]
          },
          "impact": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ]
          }
        },
        "required": [
          "itemKey",
          "title",
          "type",
          "impact"
        ]
      },
      "ActionItemLinkRequest": {
        "type": "object",
        "properties": {
          "itemKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512
          },
          "url": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2048,
            "description": "An absolute http(s) URL."
          },
          "label": {
            "type": "string",
            "maxLength": 200
          }
        },
        "required": [
          "itemKey",
          "url"
        ]
      },
      "ActionItemQuoteRequest": {
        "type": "object",
        "properties": {
          "itemKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512
          },
          "note": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 1000
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "itemKey"
        ]
      },
      "ContentBriefCreateRequest": {
        "type": "object",
        "properties": {
          "contentPieceIndex": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "contentPieceIndex"
        ]
      },
      "EntityTypeRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "kind": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "place",
                  "ai_platform",
                  "person",
                  "publisher",
                  "generic"
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "name",
          "kind"
        ]
      },
      "EntityMergeRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "into": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "name",
          "into"
        ]
      },
      "EntityImportRequest": {
        "type": "object",
        "properties": {
          "csv": {
            "type": "string",
            "maxLength": 200000
          }
        },
        "required": [
          "csv"
        ]
      },
      "ConnectorSelectability": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string"
            },
            "label": {
              "type": "string"
            },
            "locked": {
              "type": "boolean"
            },
            "preselected": {
              "type": "boolean"
            },
            "reason": {
              "type": "string",
              "enum": [
                "ok",
                "plan_pinned",
                "over_cap"
              ]
            }
          },
          "required": [
            "type",
            "label",
            "locked",
            "preselected",
            "reason"
          ],
          "additionalProperties": true
        }
      },
      "ConnectorSelection": {
        "type": "object",
        "properties": {
          "connectorTypes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "selectability": {
            "$ref": "#/components/schemas/ConnectorSelectability"
          },
          "maxConnectors": {
            "type": "integer"
          }
        },
        "required": [
          "connectorTypes"
        ],
        "additionalProperties": true
      },
      "AuditCompetitors": {
        "type": "object",
        "properties": {
          "competitors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "domain": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "sizeTier": {
                  "type": "string",
                  "enum": [
                    "startup",
                    "smb",
                    "mid-market",
                    "enterprise",
                    "unknown"
                  ]
                },
                "classification": {
                  "type": "string",
                  "enum": [
                    "direct",
                    "indirect",
                    "not-competitor"
                  ],
                  "description": "`not-competitor` is a person's verdict; a run never overrides it."
                },
                "evidence": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Why this is a competitor. Absent until a run surfaces evidence."
                }
              },
              "required": [
                "name",
                "domain"
              ],
              "additionalProperties": true
            }
          }
        },
        "required": [
          "competitors"
        ],
        "additionalProperties": true
      },
      "AuditTargeting": {
        "type": "object",
        "properties": {
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "ISO 639-1 codes the prompts are written in."
          },
          "locations": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The location answers are requested from. At most one."
          },
          "languageSuggestions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Languages that fit this audit, for a picker."
          },
          "locationSuggestions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Locations that fit this audit, for a picker."
          }
        },
        "required": [
          "languages",
          "locations",
          "languageSuggestions",
          "locationSuggestions"
        ],
        "additionalProperties": true
      },
      "EntityEditResult": {
        "type": "object",
        "properties": {
          "nameKey": {
            "type": [
              "string",
              "null"
            ],
            "description": "The key the name files under."
          },
          "outcome": {
            "type": "string",
            "enum": [
              "applied",
              "unchanged"
            ],
            "description": "`unchanged` when the name already read that way; nothing was written."
          }
        },
        "required": [
          "nameKey",
          "outcome"
        ],
        "additionalProperties": true
      },
      "Prompt": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "selected": {
            "type": "boolean",
            "description": "Whether the next run asks this prompt."
          },
          "angleId": {
            "type": "string"
          },
          "angleLabel": {
            "type": "string"
          },
          "querySubject": {
            "type": "string"
          },
          "funnelStage": {
            "type": [
              "string",
              "null"
            ]
          },
          "isCustom": {
            "type": "boolean",
            "description": "Written by a person rather than generated."
          },
          "branded": {
            "type": "boolean",
            "description": "Whether the prompt names the brand."
          },
          "language": {
            "type": [
              "string",
              "null"
            ]
          },
          "promptType": {
            "type": "string",
            "enum": [
              "UNBRANDED",
              "BRANDED",
              "RECALL"
            ]
          },
          "topicId": {
            "type": [
              "string",
              "null"
            ]
          },
          "region": {
            "type": [
              "string",
              "null"
            ]
          },
          "firstParty": {
            "type": "object",
            "properties": {
              "source": {
                "type": "string"
              },
              "term": {
                "type": "string"
              }
            },
            "required": [
              "source",
              "term"
            ],
            "additionalProperties": true
          },
          "mined": {
            "type": "object",
            "properties": {
              "questionId": {
                "type": "string"
              },
              "seedKeyword": {
                "type": "string"
              },
              "sourceKind": {
                "type": "string"
              },
              "seedSource": {
                "type": "string"
              },
              "firstSeenAt": {
                "type": "string",
                "format": "date-time"
              },
              "answerDomains": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "questionId",
              "answerDomains"
            ],
            "additionalProperties": true
          }
        },
        "required": [
          "id",
          "text",
          "selected",
          "angleId",
          "angleLabel",
          "isCustom",
          "branded",
          "promptType"
        ],
        "additionalProperties": true
      },
      "PromptSet": {
        "type": "object",
        "properties": {
          "ready": {
            "type": "boolean"
          },
          "status": {
            "type": "string"
          },
          "prompts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Prompt"
            }
          },
          "maxQueries": {
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "ready",
          "status",
          "prompts"
        ],
        "additionalProperties": true
      },
      "PromptRemoval": {
        "type": "object",
        "properties": {
          "prompts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Prompt"
            }
          },
          "maxQueries": {
            "type": [
              "integer",
              "null"
            ]
          },
          "removed": {
            "type": "string",
            "enum": [
              "archived",
              "deleted"
            ]
          }
        },
        "required": [
          "prompts",
          "maxQueries",
          "removed"
        ],
        "additionalProperties": true
      },
      "PromptCapacity": {
        "type": "object",
        "properties": {
          "used": {
            "type": "integer",
            "description": "Selected prompts."
          },
          "cap": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The plan's ceiling on selected prompts; `null` when there is none."
          },
          "left": {
            "type": [
              "integer",
              "null"
            ],
            "description": "How many more may be selected; `null` when there is no ceiling."
          }
        },
        "required": [
          "used",
          "cap",
          "left"
        ],
        "additionalProperties": true
      },
      "PromptImportReport": {
        "type": "object",
        "properties": {
          "dryRun": {
            "type": "boolean"
          },
          "counts": {
            "type": "object",
            "properties": {
              "added": {
                "type": "integer"
              },
              "restored": {
                "type": "integer"
              },
              "over_capacity": {
                "type": "integer"
              },
              "duplicate": {
                "type": "integer"
              },
              "invalid": {
                "type": "integer"
              }
            },
            "required": [
              "added",
              "restored",
              "over_capacity",
              "duplicate",
              "invalid"
            ],
            "additionalProperties": true
          },
          "topics": {
            "type": "object",
            "properties": {
              "matched": {
                "type": "integer"
              },
              "created": {
                "type": "integer"
              }
            },
            "required": [
              "matched",
              "created"
            ],
            "additionalProperties": true
          },
          "ignoredColumns": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "maxQueries": {
            "type": [
              "integer",
              "null"
            ]
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "row": {
                  "type": "integer",
                  "description": "1-based data row; the header is row 0."
                },
                "outcome": {
                  "type": "string",
                  "enum": [
                    "added",
                    "restored",
                    "over_capacity",
                    "duplicate",
                    "invalid"
                  ]
                },
                "reason": {
                  "type": "string",
                  "enum": [
                    "too_short",
                    "too_long",
                    "blank",
                    "archived_in_file",
                    "duplicate_in_file",
                    "topic_limit",
                    "topic_too_long"
                  ]
                },
                "promptId": {
                  "type": "string"
                },
                "topicSet": {
                  "type": "boolean"
                }
              },
              "required": [
                "row",
                "outcome"
              ],
              "additionalProperties": true
            }
          }
        },
        "required": [
          "dryRun",
          "counts",
          "topics",
          "ignoredColumns",
          "maxQueries",
          "rows"
        ],
        "additionalProperties": true
      },
      "AuditTopic": {
        "type": "object",
        "properties": {
          "topic": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "label": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "label"
            ],
            "additionalProperties": true
          }
        },
        "required": [
          "topic"
        ],
        "additionalProperties": true
      },
      "BrandFact": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "factKey": {
            "type": "string",
            "enum": [
              "claim",
              "phone",
              "address",
              "hours",
              "primary_category",
              "service_area",
              "headquarters",
              "founded_year",
              "founder",
              "pricing_model",
              "price_range",
              "certification",
              "offering"
            ]
          },
          "value": {
            "type": "string"
          },
          "sourceUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "origin": {
            "type": "string",
            "enum": [
              "user",
              "places",
              "claims_migration",
              "inherited"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "draft",
              "confirmed",
              "rejected"
            ]
          },
          "decidedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "supersededAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When a newer value replaced it; `null` while current."
          },
          "createdByUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "factKey",
          "value",
          "sourceUrl",
          "origin",
          "state",
          "decidedAt",
          "supersededAt",
          "createdByUserId",
          "createdAt"
        ],
        "additionalProperties": true
      },
      "BrandFactDecision": {
        "type": "object",
        "properties": {
          "fact": {
            "$ref": "#/components/schemas/BrandFact"
          }
        },
        "required": [
          "fact"
        ],
        "additionalProperties": true
      },
      "SourceTypeOverride": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string"
          },
          "pathPrefix": {
            "type": "string"
          },
          "sourceType": {
            "type": "string",
            "enum": [
              "forum",
              "qa",
              "review_site",
              "directory",
              "video",
              "social",
              "news",
              "blog",
              "reference",
              "code",
              "vendor",
              "search_engine",
              "other"
            ]
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "domain",
          "pathPrefix",
          "sourceType",
          "updatedAt"
        ],
        "additionalProperties": true
      },
      "ReferralPull": {
        "type": [
          "object",
          "null"
        ],
        "properties": {
          "pulledAt": {
            "type": "string",
            "format": "date-time"
          },
          "windowDays": {
            "type": "integer"
          },
          "rawRows": {
            "type": [
              "integer",
              "null"
            ]
          },
          "sampleInterval": {
            "type": [
              "number",
              "null"
            ],
            "description": "GA4's sampling interval; `null` when the pull was unsampled."
          }
        },
        "required": [
          "pulledAt",
          "windowDays",
          "rawRows",
          "sampleInterval"
        ],
        "additionalProperties": true,
        "description": "The last referral pull; `null` before the first."
      },
      "UserActionItem": {
        "type": "object",
        "properties": {
          "itemKey": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "subtitle": {
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "on-page",
              "off-page",
              "technical"
            ]
          },
          "impact": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ]
          }
        },
        "required": [
          "itemKey",
          "title",
          "subtitle",
          "type",
          "impact"
        ],
        "additionalProperties": true
      },
      "ActionItemLink": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "itemKey": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "label": {
            "type": [
              "string",
              "null"
            ]
          },
          "firstVerifiedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "The first time a run found the link live or cited."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "outcome": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "crawlVisible": {
                "type": [
                  "boolean",
                  "null"
                ],
                "description": "On the audited site: present in the crawl and answering 2xx/3xx. `null` off-site."
              },
              "crawlDetail": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "crawlAgeDays": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Age of the crawl this was measured against."
              },
              "cited": {
                "type": [
                  "boolean",
                  "null"
                ],
                "description": "AI answers cited this exact URL."
              },
              "domainCited": {
                "type": [
                  "boolean",
                  "null"
                ],
                "description": "AI answers cited its domain. Off-site links only."
              },
              "ranking": {
                "type": [
                  "boolean",
                  "null"
                ],
                "description": "The page ranks in search. On-site links only."
              },
              "position": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "checkedAt": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "crawlVisible",
              "cited",
              "checkedAt"
            ],
            "additionalProperties": true,
            "description": "The newest check against the latest snapshot; `null` until one ran."
          }
        },
        "required": [
          "id",
          "itemKey",
          "url",
          "label",
          "firstVerifiedAt",
          "createdAt",
          "outcome"
        ],
        "additionalProperties": true
      },
      "ActionItemQuote": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "itemKey": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "REQUESTED",
              "QUOTED",
              "NEEDS_CALL",
              "DECLINED"
            ]
          },
          "itemTitle": {
            "type": "string",
            "description": "The item as it read when the quote was requested."
          },
          "itemSummary": {
            "type": [
              "string",
              "null"
            ]
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          },
          "replies": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "outcome": {
                  "type": "string",
                  "enum": [
                    "QUOTED",
                    "NEEDS_CALL",
                    "DECLINED"
                  ]
                },
                "priceCents": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Set only on a `QUOTED` reply."
                },
                "message": {
                  "type": "string"
                },
                "sentBy": {
                  "type": "string"
                },
                "sentAt": {
                  "type": "string",
                  "format": "date-time"
                }
              },
              "required": [
                "outcome",
                "priceCents",
                "message",
                "sentAt"
              ],
              "additionalProperties": true
            },
            "description": "Beket's answers, oldest first."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "itemKey",
          "status",
          "itemTitle",
          "replies",
          "createdAt"
        ],
        "additionalProperties": true
      },
      "ActionItemQuoteResult": {
        "type": "object",
        "properties": {
          "quote": {
            "$ref": "#/components/schemas/ActionItemQuote"
          }
        },
        "required": [
          "quote"
        ],
        "additionalProperties": true
      },
      "ContentBriefPayload": {
        "type": "object",
        "properties": {
          "targetQueries": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "angle": {
                  "type": "string"
                },
                "queryText": {
                  "type": "string"
                },
                "expectedAiResponseFormat": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "suggestedContentType": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "angle",
                "queryText",
                "expectedAiResponseFormat",
                "suggestedContentType"
              ]
            }
          },
          "answerEngineFormat": {
            "type": "string"
          },
          "schemaRecommendations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sourceStrategy": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "sourceGapDomain": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "approach": {
                  "type": "string"
                }
              },
              "required": [
                "sourceGapDomain",
                "approach"
              ]
            }
          },
          "citationPlan": {
            "type": "string"
          },
          "outline": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "heading": {
                  "type": "string"
                },
                "level": {
                  "anyOf": [
                    {
                      "type": "number",
                      "const": 2
                    },
                    {
                      "type": "number",
                      "const": 3
                    }
                  ]
                },
                "keyPoints": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "required": [
                "heading",
                "level",
                "keyPoints"
              ]
            }
          },
          "wordCountTarget": {
            "type": "number"
          },
          "introAngle": {
            "type": "string"
          },
          "competitorQuotesToBeat": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "competitorName": {
                  "type": "string"
                },
                "quote": {
                  "type": "string"
                }
              },
              "required": [
                "competitorName",
                "quote"
              ]
            }
          },
          "topicOwnershipContext": {
            "type": "string"
          },
          "suggestedInternalLinks": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string"
                },
                "title": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "anchorRationale": {
                  "type": "string"
                }
              },
              "required": [
                "url",
                "title",
                "anchorRationale"
              ]
            }
          }
        },
        "required": [
          "targetQueries",
          "answerEngineFormat",
          "schemaRecommendations",
          "sourceStrategy",
          "citationPlan",
          "outline",
          "wordCountTarget",
          "introAngle",
          "competitorQuotesToBeat",
          "topicOwnershipContext",
          "suggestedInternalLinks"
        ]
      },
      "ContentBriefSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "auditId": {
            "type": "string"
          },
          "contentPieceIndex": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The roadmap piece it was generated from."
          },
          "sourcePiece": {
            "type": "object",
            "additionalProperties": true,
            "description": "The roadmap piece as it stood when the brief was created."
          },
          "version": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "GENERATING",
              "READY",
              "FAILED"
            ],
            "description": "PENDING and GENERATING are in progress; poll until READY or FAILED."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "auditId",
          "contentPieceIndex",
          "sourcePiece",
          "version",
          "status",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": true
      },
      "ContentBrief": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "auditId": {
            "type": "string"
          },
          "contentPieceIndex": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The roadmap piece it was generated from."
          },
          "sourcePiece": {
            "type": "object",
            "additionalProperties": true,
            "description": "The roadmap piece as it stood when the brief was created."
          },
          "version": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "GENERATING",
              "READY",
              "FAILED"
            ],
            "description": "PENDING and GENERATING are in progress; poll until READY or FAILED."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "payload": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ContentBriefPayload"
              },
              {
                "type": "null"
              }
            ],
            "description": "The generated brief; `null` until READY."
          },
          "editedPayload": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ContentBriefPayload"
              },
              {
                "type": "null"
              }
            ],
            "description": "An edit saved in the dashboard; drafts are written from it when set."
          }
        },
        "required": [
          "id",
          "auditId",
          "contentPieceIndex",
          "sourcePiece",
          "version",
          "status",
          "createdAt",
          "updatedAt",
          "payload",
          "editedPayload"
        ],
        "additionalProperties": true
      },
      "ContentDraft": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "briefId": {
            "type": "string"
          },
          "auditId": {
            "type": "string"
          },
          "version": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "GENERATING",
              "READY",
              "FAILED"
            ],
            "description": "PENDING and GENERATING are in progress; poll until READY or FAILED."
          },
          "content": {
            "type": [
              "string",
              "null"
            ],
            "description": "The draft as Markdown. Only the single-draft read fills it."
          },
          "contentMeta": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "title": {
                "type": "string"
              },
              "metaDescription": {
                "type": "string"
              },
              "jsonLd": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Suggested JSON-LD blocks, serialized."
              },
              "wordCount": {
                "type": "integer"
              }
            },
            "required": [
              "title",
              "metaDescription",
              "jsonLd",
              "wordCount"
            ],
            "additionalProperties": true
          },
          "violations": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true,
              "description": "One breach of the organization's content guidelines: `type`, `rule`, `excerpt`, `index`, `message`."
            },
            "description": "Guideline breaches found in the draft, capped; see `violationsTruncated`."
          },
          "violationsTruncated": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "briefId",
          "auditId",
          "version",
          "status",
          "content",
          "contentMeta",
          "violations",
          "violationsTruncated",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": true
      },
      "RecomputeJob": {
        "type": "object",
        "properties": {
          "auditId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "const": "RECOMPUTING_AUDIT"
          }
        },
        "required": [
          "auditId",
          "status"
        ],
        "additionalProperties": true
      },
      "SnapshotDiff": {
        "type": "object",
        "properties": {
          "snapshotA": {
            "type": "string"
          },
          "snapshotB": {
            "type": "string"
          },
          "queryChanges": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "added",
                    "removed",
                    "changed"
                  ]
                },
                "before": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "The prompt as frozen in snapshot A."
                },
                "after": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "The prompt as frozen in snapshot B."
                }
              },
              "required": [
                "key",
                "type"
              ],
              "additionalProperties": true
            },
            "description": "At most 500; see `queryChangesTruncated`."
          },
          "queryChangeCounts": {
            "type": "object",
            "properties": {
              "added": {
                "type": "integer"
              },
              "removed": {
                "type": "integer"
              },
              "changed": {
                "type": "integer"
              }
            },
            "required": [
              "added",
              "removed",
              "changed"
            ],
            "additionalProperties": true,
            "description": "Exact, including rows past the cap."
          },
          "queryChangesTruncated": {
            "type": "boolean"
          },
          "metricChanges": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "metric": {
                  "type": "string"
                },
                "before": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "after": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "delta": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              },
              "required": [
                "key",
                "metric",
                "before",
                "after",
                "delta"
              ],
              "additionalProperties": true
            },
            "description": "One row per metric per answer that moved. At most 5000; see `metricChangesTruncated`."
          },
          "metricChangeCounts": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "improved": {
                  "type": "integer"
                },
                "declined": {
                  "type": "integer"
                },
                "appeared": {
                  "type": "integer"
                },
                "disappeared": {
                  "type": "integer"
                }
              },
              "required": [
                "improved",
                "declined",
                "appeared",
                "disappeared"
              ],
              "additionalProperties": true
            },
            "description": "Exact totals per metric, including rows past the cap."
          },
          "metricChangesTruncated": {
            "type": "boolean"
          },
          "competitorChanges": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "description": "Display name."
                },
                "id": {
                  "type": "string",
                  "description": "The identity the two sides were matched on."
                },
                "domain": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "beforeRank": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "afterRank": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "beforeMentions": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "afterMentions": {
                  "type": [
                    "integer",
                    "null"
                  ]
                }
              },
              "required": [
                "key",
                "id",
                "domain",
                "beforeRank",
                "afterRank",
                "beforeMentions",
                "afterMentions"
              ],
              "additionalProperties": true
            }
          },
          "sourceChanges": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "change": {
                  "type": "string",
                  "enum": [
                    "opened",
                    "closed"
                  ]
                },
                "before": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "The source on side A."
                },
                "after": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "The source on side B."
                }
              },
              "required": [
                "key",
                "change"
              ],
              "additionalProperties": true
            }
          },
          "synthesisChanges": {
            "type": "object",
            "properties": {
              "winnableQueries": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "A winnable prompt whose score, coverage or competitors moved."
                }
              },
              "contentRoadmapChanges": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "A content roadmap item that was added, removed or changed."
                }
              },
              "provenanceChanges": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "key": {
                      "type": "string"
                    },
                    "beforeDomains": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "afterDomains": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "key",
                    "beforeDomains",
                    "afterDomains"
                  ],
                  "additionalProperties": true
                }
              }
            },
            "required": [
              "winnableQueries",
              "contentRoadmapChanges",
              "provenanceChanges"
            ],
            "additionalProperties": true
          },
          "unavailable": {
            "type": "object",
            "properties": {
              "a": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "b": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "a",
              "b"
            ],
            "additionalProperties": true,
            "description": "Inputs a side no longer has — archived or pruned. An empty facet over a missing input means \"unknown\", not \"unchanged\"."
          },
          "comparable": {
            "type": "boolean",
            "description": "False when the two snapshots were measured under different conditions."
          },
          "incomparableReason": {
            "type": "string",
            "enum": [
              "model-change",
              "backend-change",
              "metrics-version-change",
              "unknown-provenance"
            ],
            "description": "Absent when `comparable` is true."
          }
        },
        "required": [
          "snapshotA",
          "snapshotB",
          "queryChanges",
          "queryChangeCounts",
          "queryChangesTruncated",
          "metricChanges",
          "metricChangeCounts",
          "metricChangesTruncated",
          "competitorChanges",
          "sourceChanges",
          "synthesisChanges",
          "unavailable",
          "comparable"
        ],
        "additionalProperties": true
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              },
              "type": {
                "type": "string"
              }
            },
            "required": [
              "message",
              "type"
            ],
            "additionalProperties": true
          }
        },
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false
      }
    },
    "parameters": {
      "auditId": {
        "name": "auditId",
        "in": "path",
        "required": true,
        "description": "The audit's id.",
        "schema": {
          "type": "string"
        }
      },
      "promptId": {
        "name": "promptId",
        "in": "path",
        "required": true,
        "description": "The prompt's id.",
        "schema": {
          "type": "string"
        }
      },
      "topicId": {
        "name": "topicId",
        "in": "path",
        "required": true,
        "description": "The topic's id.",
        "schema": {
          "type": "string"
        }
      },
      "factId": {
        "name": "factId",
        "in": "path",
        "required": true,
        "description": "The fact's id.",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "ValidationFailed": {
        "description": "The request body or a parameter failed validation.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, malformed, revoked, or expired credentials.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "PaymentRequired": {
        "description": "This organization's plan does not include programmatic API access.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The key is read-only and the request is a mutation, or the caller's role does not permit it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "No such resource, or it belongs to another organization.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded. Retry after the window closes.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "ServerError": {
        "description": "Unexpected server error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
