{
  "openapi": "3.0.3",
  "info": {
    "title": "Qwairy API",
    "description": "Track your brand's visibility across AI platforms like ChatGPT, Claude, Perplexity, and Gemini.\n\n## Authentication\nAll endpoints require a Bearer token in the Authorization header:\n```\nAuthorization: Bearer qw-api-xxxxxxxxxxxxx\n```\n\nCreate API keys from Team Management > REST API.\n\n## Write access\nRead endpoints are available from Growth, except Crawler Analytics and the\nwebhook endpoints, which require an active Business, Agency Business or\nEnterprise plan. Write endpoints additionally require an active Business,\nAgency Business or Enterprise plan.\n\nWrites are disabled on every API key until an Owner or Manager enables them\nfor that key in Team Management > REST API. A key without write access\nreceives 403 API_KEY_READ_ONLY, which does not count against the write quota.\n\n## Writing safely\n- Every mutating `POST` requires an `Idempotency-Key`. Replaying the same\n  key with the same body for 24 hours returns the original response; reusing\n  it with a different body returns `409`. Definitive `4xx` responses after\n  command execution begins are also replayed. Resolve the rejection and\n  reconcile resource state before submitting a new logical operation with\n  a new key. If a connection is lost while a\n  request remains in flight, reconcile the resource before using a new key;\n  Qwairy never guesses and executes an uncertain effect twice.\n  Until that outcome is known, the same key returns `409\n  IDEMPOTENCY_IN_PROGRESS`. A replayed response carries\n  `Idempotent-Replay: true`.\n- `PATCH` and versioned `DELETE` require `If-Match` carrying the\n  `ETag` you last read. A missing header returns `428`, a stale one `412`.\n  Qwairy emits the strong form (`\"7\"`); a response compressed in transit\n  can carry the weak form (`W/\"7\"`) of the same version. `If-Match`\n  accepts both forms.\n- Errors carry a stable `error.code` and a `requestId` to quote in support.\n  Every write response carries `X-Request-Id` and `Cache-Control: private,\n  no-store`. On an error, `X-Request-Id` equals `error.requestId`, except\n  on a replayed response (`Idempotent-Replay: true`), whose body keeps the\n  `requestId` of the original request.\n- A resource belonging to another team always returns `404`.\n- A write refused with `429` changed nothing: retry after the\n  `Retry-After` seconds.\n\n## Rate Limiting\n- Write endpoints have their own budget: 120 requests per minute and 5,000 per day per team.\n- The read defaults below and their team-specific overrides do not change the separate write budget.\n- Default: 1,000 requests per minute per team\n- Default: 20,000 requests per day per team\n- Team-specific limits may override these defaults\n- Quota headers are returned only after authentication, paid-surface admission, and a completed rate-limit check\n- Both successful responses and errors after that check include the checked burst and daily windows\n- Authentication refusals and paid-surface refusals before the check have no quota headers\n- `RateLimit-Policy` and `RateLimit` are omitted if either window check times out or fails\n- Legacy `X-RateLimit-*` fields can contain zero values on a resolved limiter timeout; use the standard fields for verified quotas\n- `RateLimit-Policy` and `RateLimit` follow sections 3 and 4 of\n  [draft-ietf-httpapi-ratelimit-headers-11](https://www.ietf.org/archive/id/draft-ietf-httpapi-ratelimit-headers-11.html),\n  an IETF Internet-Draft, not a final RFC\n- Each field is a Structured Fields list of strings with parameters, for example:\n  `RateLimit-Policy: \"burst\";q=1000;w=60, \"daily\";q=20000;w=86400` and\n  `RateLimit: \"burst\";r=999;t=60, \"daily\";r=19999;t=86400`\n- `q` is the allocated request quota, `w` is the window in seconds, `r` is the remaining quota,\n  and `t` is a non-negative integer delta in seconds until the end of the current effective window, not an absolute timestamp\n- `t` is a limiter window hint and does not guarantee complete quota renewal when that window ends\n- Legacy `X-RateLimit-*` burst and daily fields remain available; their reset fields are ISO 8601 timestamps\n- On HTTP 429, honor `Retry-After` for the blocking window (burst or daily); a positive remaining quota is not a guarantee of admission\n\n## Base URL\n```\nhttps://www.qwairy.co/api/v1\n```\n\n## Unknown endpoints and log ingestion\nUndefined paths return `404` with `error.code: ENDPOINT_NOT_FOUND` for\nGET, POST, PUT, PATCH and DELETE. The catch-all OPTIONS handler returns\n`204` for CORS preflight. The `/logs/*` ingestion routes use a separate\ningestion contract and are outside this customer API specification.\n",
    "version": "1.0.0",
    "contact": {
      "email": "team@qwairy.co",
      "url": "https://qwairy.co"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://qwairy.co/legal/terms"
    }
  },
  "servers": [
    {
      "url": "https://www.qwairy.co/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Brands",
      "description": "Manage and list brands in your account"
    },
    {
      "name": "Performance",
      "description": "Brand performance metrics and GEO scores"
    },
    {
      "name": "Crawler Analytics",
      "description": "Aggregated AI crawler activity observed in server logs"
    },
    {
      "name": "Competitors",
      "description": "Track competitor mentions and share of voice"
    },
    {
      "name": "Sources",
      "description": "Monitor cited source domains and individual source URLs"
    },
    {
      "name": "Actions",
      "description": "Read prioritized Action Center recommendations and update their status"
    },
    {
      "name": "Content",
      "description": "Export Content Studio articles to an external CMS"
    },
    {
      "name": "Matrix",
      "description": "Compare brand visibility by topic, tag, prompt or funnel stage and provider"
    },
    {
      "name": "Perception",
      "description": "Monthly brand perception scores and completed snapshot details"
    },
    {
      "name": "Shopping",
      "description": "Product recommendations extracted from AI responses"
    },
    {
      "name": "Local",
      "description": "Local business recommendations extracted from AI responses"
    },
    {
      "name": "Social",
      "description": "Social and forum citations in AI responses"
    },
    {
      "name": "Sponsored",
      "description": "Sponsored placements detected in AI responses"
    },
    {
      "name": "Technical Analysis",
      "description": "Stored technical file analyses and AI Readiness scores"
    },
    {
      "name": "Prompts",
      "description": "Access monitored prompts and queries"
    },
    {
      "name": "Answers",
      "description": "Retrieve AI-generated responses and analysis"
    },
    {
      "name": "Search",
      "description": "Query fan-out and AI search insights"
    },
    {
      "name": "Keywords",
      "description": "Track keyword/topic performance metrics"
    },
    {
      "name": "Tags",
      "description": "Track tag performance metrics"
    },
    {
      "name": "Monitoring",
      "description": "Configure and pause workspace monitoring"
    },
    {
      "name": "Runs",
      "description": "Estimate and start generation runs"
    },
    {
      "name": "Credits",
      "description": "Credit balance, consumption and runway"
    },
    {
      "name": "Pitch Audits",
      "description": "Create, review and read agency prospect audits"
    },
    {
      "name": "Site Diagnostics",
      "description": "Monitored pages, page audits and the issues found on them"
    },
    {
      "name": "Prompt Suggestions",
      "description": "Generate Prompt Studio suggestions and accept them as prompts"
    },
    {
      "name": "Webhooks",
      "description": "Signed notifications of finished work, sent to the endpoints of the team.\nEach delivery is an HTTPS POST of a WebhookEventEnvelope with these\nheaders: Content-Type application/json; X-Qwairy-Event, the event type;\nX-Qwairy-Delivery, the delivery identifier for this endpoint;\nX-Qwairy-Timestamp, Unix seconds at signing; X-Qwairy-Signature,\n`sha256=` followed by the hex HMAC-SHA256 of `<timestamp>.<raw body>`\nkeyed with the endpoint secret (`qwhsec_...`). During the 24 hours after\na rotation, X-Qwairy-Signature holds two comma-separated values, the new\nsecret first; accept a delivery when one of them matches. Compare in\nconstant time and reject old timestamps.\n\nAnswer with any 2xx within 10 seconds. Other answers, timeouts and\nconnection errors are retried on the schedule described in\nWebhookEventType. Once deliveries have failed without any success for 72\nhours, the next failed attempt disables the endpoint (disabledReason\nFAILING). Retries and redeliveries repeat the\nsame envelope id and X-Qwairy-Delivery: process deliveries idempotently\non those identifiers.\n"
    }
  ],
  "paths": {
    "/brands": {
      "get": {
        "tags": [
          "Brands"
        ],
        "summary": "List active brands",
        "description": "Returns your team's active brands that are not being transferred",
        "operationId": "listBrands",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "total": {
                      "type": "integer",
                      "example": 2
                    },
                    "brands": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BrandSummary"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by lifecycle status. Omitted, only LIVE workspaces are\nreturned, which preserves the historical behaviour.\n",
            "schema": {
              "type": "string",
              "enum": [
                "LIVE",
                "DRAFT",
                "ARCHIVED",
                "ALL"
              ]
            }
          }
        ]
      },
      "post": {
        "tags": [
          "Brands"
        ],
        "summary": "Create a workspace",
        "description": "Creates a workspace in DRAFT. No analysis, description generation or\nbillable run is started: activate it with a separate PATCH once it is\nconfigured.\nA DRAFT workspace does not use a workspace of the plan: the limit is\nchecked when it goes LIVE. languageCode and countryCode default to FR.\nA domain already used by another workspace of the team, or a team that\nis not active, returns 409 CONFLICT. Each creation also spends a\nrolling 24-hour budget equal to the team's workspace limit, and at\nleast 5; once it is spent, the request returns 429 with\ndetails.reason BRAND_CREATION_DAILY_LIMIT and Retry-After.\n",
        "operationId": "createWorkspace",
        "parameters": [
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "domain"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "domain": {
                    "type": "string",
                    "description": "Bare hostname, without scheme or path",
                    "maxLength": 253,
                    "pattern": "^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,24}$"
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 2000,
                    "nullable": true
                  },
                  "languageCode": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 2,
                    "pattern": "^[A-Za-z]{2}$"
                  },
                  "countryCode": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 2,
                    "pattern": "^[A-Za-z]{2}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Workspace created",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "workspace": {
                      "$ref": "#/components/schemas/Workspace"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}": {
      "get": {
        "tags": [
          "Brands"
        ],
        "summary": "Get brand details",
        "description": "Returns the mutable workspace representation and summary counts. DRAFT\nand ARCHIVED workspaces remain readable so their ETag can be used for a\nlater lifecycle transition.\n",
        "operationId": "getBrand",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "brand": {
                      "$ref": "#/components/schemas/BrandDetail"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          }
        ]
      },
      "patch": {
        "tags": [
          "Brands"
        ],
        "summary": "Update a workspace",
        "description": "Updates workspace properties and drives its lifecycle. Allowed\ntransitions are DRAFT to LIVE or ARCHIVED, LIVE to ARCHIVED and ARCHIVED\nback to LIVE. Archiving returns 409 while answers are still being\ngenerated, and no transition ever starts generation implicitly.\nAs in the dashboard, archiving is available to agencies, or to any team\nwhile it has more active workspaces than its plan includes (otherwise\n403 INSUFFICIENT_PLAN), and restoring an archived workspace returns 409\nwhile another active workspace tracks the same domain for the same\nlanguage and country. countryCode must be an ISO 3166-1 alpha-2 code.\nThe profile fields url, countryCodes, autoDetectCompetitors and\nselfHostScope can be changed in the same call; the domain cannot.\nMoving a workspace to LIVE returns 409 QUOTA_EXCEEDED when the plan's\nworkspace limit is reached. A workspace locked because the team uses\nmore workspaces than its plan includes can only be archived; any other\nchange returns 409 QUOTA_EXCEEDED.\n",
        "operationId": "updateWorkspace",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/ifMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string",
                    "nullable": true
                  },
                  "languageCode": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 2,
                    "pattern": "^[A-Za-z]{2}$"
                  },
                  "countryCode": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 2,
                    "pattern": "^[A-Za-z]{2}$"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "DRAFT",
                      "LIVE",
                      "ARCHIVED"
                    ]
                  },
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 2048,
                    "nullable": true,
                    "description": "Workspace URL on the workspace domain (http or https), or null to clear it. The domain itself cannot be changed."
                  },
                  "countryCodes": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 50,
                    "items": {
                      "type": "string",
                      "pattern": "^[A-Z]{2}$"
                    },
                    "description": "Complete replacement of the workspace country catalog; the default country stays first. Removing a country removes it from the prompts that selected it."
                  },
                  "autoDetectCompetitors": {
                    "type": "boolean",
                    "description": "Whether competitors are detected automatically in answers."
                  },
                  "selfHostScope": {
                    "type": "string",
                    "enum": [
                      "REGISTRABLE",
                      "EXACT_HOST"
                    ],
                    "description": "REGISTRABLE counts every host of the registrable domain as the brand; EXACT_HOST only the configured host and its subdomains. A read can return AUTO, which a write does not accept."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Workspace updated",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "workspace": {
                      "$ref": "#/components/schemas/Workspace"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}/performance": {
      "get": {
        "tags": [
          "Performance"
        ],
        "summary": "Get performance snapshot",
        "description": "Returns aggregated performance metrics for a brand",
        "operationId": "getPerformance",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PerformanceSnapshot"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/topic"
          },
          {
            "$ref": "#/components/parameters/tag"
          },
          {
            "$ref": "#/components/parameters/promptType"
          }
        ]
      }
    },
    "/brands/{brandId}/crawler-analytics": {
      "get": {
        "tags": [
          "Crawler Analytics"
        ],
        "summary": "Get AI crawler analytics",
        "description": "Returns retained daily AI crawler aggregates for a brand, including activity over\ntime, crawler distribution, page states, HTTP status groups, coverage, and pagination.\nPage detail is available for 30 days; first seen, last crawled, and lifetime volume\nremain available from the durable page inventory. Raw server logs and human traffic\nare neither returned nor retained.\nBy default the pages array lists only pages with at least one occurrence in the\nrange, and pagination totals describe that list. Set activeOnly=false to list the\ndurable page inventory instead, including pages without occurrences in the range.\nRequires an active Business, Agency Business or Enterprise plan;\nauthenticated teams without this entitlement receive 403.\n",
        "operationId": "getCrawlerAnalytics",
        "responses": {
          "200": {
            "description": "Aggregated crawler analytics with explicit coverage semantics",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CrawlerAnalyticsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/InsufficientPlan"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "description": "An unexpected server error occurred",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/InternalServerError"
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "name": "range",
            "in": "query",
            "description": "Retained range. Defaults to 30d.",
            "schema": {
              "type": "string",
              "enum": [
                "24h",
                "7d",
                "30d"
              ],
              "default": "30d"
            }
          },
          {
            "name": "state",
            "in": "query",
            "description": "Filter the listed pages by computed state. Applies to active pages by default, and to the durable inventory with activeOnly=false.",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "new",
                "hot"
              ],
              "default": "all"
            }
          },
          {
            "name": "activeOnly",
            "in": "query",
            "description": "Defaults to true, also when omitted: only pages with at least one occurrence in\nthe range are listed. Set to false to list the durable page inventory, including\npages without occurrences in the range. That listing ranks and counts every known\npage and is markedly slower on large inventories.\n",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "One-based page number for the pages array.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10000,
              "default": 1
            }
          },
          {
            "$ref": "#/components/parameters/limit"
          }
        ]
      }
    },
    "/brands/{brandId}/competitors": {
      "get": {
        "tags": [
          "Competitors"
        ],
        "summary": "List competitors",
        "description": "Returns competitors with metrics, excluding ignored competitors. Defaults to SELF and DIRECT relationships.",
        "operationId": "listCompetitors",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "competitors": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Competitor"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/topic"
          },
          {
            "$ref": "#/components/parameters/tag"
          },
          {
            "$ref": "#/components/parameters/promptType"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "mentions",
                "position",
                "sentiment",
                "shareOfVoice",
                "name"
              ],
              "default": "mentions"
            }
          },
          {
            "$ref": "#/components/parameters/order"
          },
          {
            "name": "relationship",
            "in": "query",
            "description": "Filter by comma-separated SELF, DIRECT, or INDIRECT values. Defaults to SELF and DIRECT.",
            "schema": {
              "type": "string",
              "default": "SELF,DIRECT"
            }
          }
        ]
      }
    },
    "/brands/{brandId}/competitors/{competitorId}": {
      "get": {
        "tags": [
          "Competitors"
        ],
        "summary": "Get competitor details",
        "description": "Returns detailed metrics for a specific competitor",
        "operationId": "getCompetitor",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "competitor": {
                      "$ref": "#/components/schemas/CompetitorDetail"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/CompetitorNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/competitorId"
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/topic"
          },
          {
            "$ref": "#/components/parameters/tag"
          }
        ]
      }
    },
    "/brands/{brandId}/competitors/{competitorId}/evolution": {
      "get": {
        "tags": [
          "Competitors"
        ],
        "summary": "Get competitor evolution",
        "description": "Returns daily evolution data for a competitor",
        "operationId": "getCompetitorEvolution",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompetitorEvolution"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/CompetitorNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/competitorId"
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/topic"
          },
          {
            "$ref": "#/components/parameters/tag"
          }
        ]
      }
    },
    "/brands/{brandId}/source-domains": {
      "get": {
        "tags": [
          "Sources"
        ],
        "summary": "List source domains",
        "description": "Returns cited domains grouped by domain and historical source type.\n`rate` is the group's citation count divided by all citation counts\nmatching the same filters, multiplied by 100 and rounded to two decimals.\nDate filters use answer creation time; an explicit date pair takes\nprecedence over period. `avgPosition` excludes zero positions.\nPagination total counts distinct source domain IDs, so a domain with\nmultiple historical source types can contribute more than one row.\n",
        "operationId": "listSources",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "sources": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Source"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/topic"
          },
          {
            "$ref": "#/components/parameters/tag"
          },
          {
            "$ref": "#/components/parameters/countries"
          },
          {
            "name": "type",
            "in": "query",
            "description": "Filter by historical source type; unmatched values return no rows",
            "schema": {
              "type": "string",
              "example": "MEDIA"
            }
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "mentions",
                "position",
                "rate",
                "domain"
              ],
              "default": "mentions"
            }
          },
          {
            "$ref": "#/components/parameters/order"
          }
        ]
      }
    },
    "/brands/{brandId}/source-domains/{sourceId}": {
      "get": {
        "tags": [
          "Sources"
        ],
        "summary": "Get source domain details",
        "description": "Returns one source domain, citation metrics, provider breakdown and\nup to ten topics. `rate` divides this domain's citation count by all\nsource citations for the brand in the selected date range, multiplied\nby 100 and rounded to two decimals. `avgPosition` includes zero\npositions in its average; a zero result is returned as null.\n",
        "operationId": "getSource",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "source": {
                      "$ref": "#/components/schemas/SourceDetail"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/SourceNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/sourceId"
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          }
        ]
      }
    },
    "/brands/{brandId}/source-domains/{sourceId}/evolution": {
      "get": {
        "tags": [
          "Sources"
        ],
        "summary": "Get source domain evolution",
        "description": "Returns daily citation counts and mean positions using answer creation dates. Only dates with matching citations are returned.",
        "operationId": "getSourceEvolution",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceEvolution"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/SourceNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/sourceId"
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/topic"
          },
          {
            "$ref": "#/components/parameters/tag"
          }
        ]
      }
    },
    "/brands/{brandId}/prompts": {
      "get": {
        "tags": [
          "Prompts"
        ],
        "summary": "List prompts",
        "description": "Returns prompts (questions) analyzed for this brand. Countries and personas filter the effective current prompt configuration, not historical answer metrics.",
        "operationId": "listPrompts",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "prompts": {
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "$ref": "#/components/schemas/Prompt"
                          },
                          {
                            "$ref": "#/components/schemas/PromptControl"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "name": "view",
            "in": "query",
            "description": "`analytics` preserves the historical metrics response. Use\n`configuration` to list the mutable fields, versions and archived\nprompts needed to rebuild the dashboard control plane.\n",
            "schema": {
              "type": "string",
              "enum": [
                "analytics",
                "configuration"
              ],
              "default": "analytics"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Prompt lifecycle filter for the configuration view",
            "schema": {
              "type": "string",
              "enum": [
                "ACTIVE",
                "ARCHIVED"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/topic"
          },
          {
            "$ref": "#/components/parameters/tag"
          },
          {
            "$ref": "#/components/parameters/promptType"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "lastGeneratedAt",
                "answersCount",
                "text",
                "createdAt"
              ],
              "default": "lastGeneratedAt"
            }
          },
          {
            "$ref": "#/components/parameters/order"
          },
          {
            "$ref": "#/components/parameters/personaIds"
          },
          {
            "$ref": "#/components/parameters/configuredCountries"
          },
          {
            "name": "include",
            "in": "query",
            "description": "Set to details to include aggregated competitor and source statistics.",
            "schema": {
              "type": "string",
              "enum": [
                "details"
              ]
            }
          }
        ]
      },
      "post": {
        "tags": [
          "Prompts"
        ],
        "summary": "Create a prompt",
        "description": "Creates a prompt with its monitoring enabled: in a LIVE workspace with\nscheduled monitoring, it runs on that schedule and adds a recurring\ncredit use. Pause it with PATCH monitoringEnabled false. A prompt with\nthe same text, even archived, returns 409 CONFLICT with\ndetails.promptId; restore an archived one instead.\n",
        "operationId": "createPrompt",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "frequency": {
                    "type": "string",
                    "nullable": true,
                    "enum": [
                      "NONE",
                      "DAILY",
                      "WEEKLY",
                      "MONTHLY"
                    ]
                  },
                  "keywordId": {
                    "type": "string",
                    "nullable": true
                  },
                  "tagIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Branded and Non-branded are system tags that the server sets on the prompt from its text, in a workspace created from v1.21. Their ids are ignored in tagIds."
                  },
                  "countryCodes": {
                    "type": "array",
                    "maxItems": 50,
                    "items": {
                      "type": "string",
                      "pattern": "^[A-Z]{2}$"
                    },
                    "description": "Countries this prompt runs in, from the workspace catalog. Empty means the default country."
                  },
                  "modelIds": {
                    "type": "array",
                    "maxItems": 30,
                    "items": {
                      "type": "string"
                    },
                    "description": "Models for this prompt only, with the same identifiers as the monitoring models field. Empty means the workspace models."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Prompt created",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "prompt": {
                      "$ref": "#/components/schemas/PromptControl"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}/prompts/bulk": {
      "post": {
        "tags": [
          "Prompts"
        ],
        "summary": "Apply a bulk prompt operation",
        "description": "Applies one operation to at most 20 prompts and returns a per-item\noutcome with HTTP 200. Unknown ids are reported as not_found rather than\nfailing the whole batch.\n",
        "operationId": "bulkUpdatePrompts",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "operation",
                  "promptIds"
                ],
                "properties": {
                  "operation": {
                    "type": "string",
                    "enum": [
                      "archive",
                      "restore",
                      "frequency",
                      "topic",
                      "tags"
                    ]
                  },
                  "promptIds": {
                    "type": "array",
                    "maxItems": 20,
                    "items": {
                      "type": "string"
                    }
                  },
                  "frequency": {
                    "type": "string",
                    "nullable": true,
                    "enum": [
                      "NONE",
                      "DAILY",
                      "WEEKLY",
                      "MONTHLY"
                    ]
                  },
                  "keywordId": {
                    "type": "string",
                    "nullable": true
                  },
                  "tagIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Used by the tags operation, which replaces the tags of every listed prompt. Branded and Non-branded are system tags that the server sets from each prompt text, in a workspace created from v1.21. Their ids are ignored in tagIds, and the replacement keeps the system tag each prompt already carries."
                  },
                  "dryRun": {
                    "type": "boolean",
                    "default": false,
                    "description": "Validate and return the result without changing anything."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bulk result",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkPromptResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}/prompts/{promptId}": {
      "get": {
        "tags": [
          "Prompts"
        ],
        "summary": "Get prompt details",
        "description": "Returns detailed information about a specific prompt",
        "operationId": "getPrompt",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "prompt": {
                      "$ref": "#/components/schemas/PromptDetail"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/PromptNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/promptId"
          },
          {
            "name": "view",
            "in": "query",
            "description": "Use configuration to read an archived prompt and its mutable fields",
            "schema": {
              "type": "string",
              "enum": [
                "analytics",
                "configuration"
              ],
              "default": "analytics"
            }
          },
          {
            "name": "include",
            "in": "query",
            "description": "Set to details to include aggregated competitor and source statistics.",
            "schema": {
              "type": "string",
              "enum": [
                "details"
              ]
            }
          }
        ]
      },
      "patch": {
        "tags": [
          "Prompts"
        ],
        "summary": "Update, archive or restore a prompt",
        "description": "Archiving is a soft delete: answers and history are preserved and a\nrestore always works. There is no public hard delete.\n",
        "operationId": "updatePrompt",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/promptId"
          },
          {
            "$ref": "#/components/parameters/ifMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "ACTIVE",
                      "ARCHIVED"
                    ]
                  },
                  "frequency": {
                    "type": "string",
                    "nullable": true,
                    "enum": [
                      "NONE",
                      "DAILY",
                      "WEEKLY",
                      "MONTHLY"
                    ]
                  },
                  "monitoringEnabled": {
                    "type": "boolean"
                  },
                  "keywordId": {
                    "type": "string",
                    "nullable": true
                  },
                  "tagIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Replaces the tags of the prompt. Branded and Non-branded are system tags that the server sets from the prompt text, in a workspace created from v1.21. Their ids are ignored in tagIds, and the replacement keeps the system tag the prompt already carries. When text changes, the server sets the system tag again from the new text."
                  },
                  "countryCodes": {
                    "type": "array",
                    "maxItems": 50,
                    "items": {
                      "type": "string",
                      "pattern": "^[A-Z]{2}$"
                    },
                    "description": "Countries this prompt runs in, from the workspace catalog. Empty means the default country."
                  },
                  "modelIds": {
                    "type": "array",
                    "maxItems": 30,
                    "items": {
                      "type": "string"
                    },
                    "description": "Models for this prompt only, with the same identifiers as the monitoring models field. Empty means the workspace models."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Prompt updated",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "prompt": {
                      "$ref": "#/components/schemas/PromptControl"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}/prompts/{promptId}/answers": {
      "get": {
        "tags": [
          "Prompts"
        ],
        "summary": "Get prompt answers",
        "description": "Returns all AI-generated responses for a specific prompt",
        "operationId": "getPromptAnswers",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "prompt": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "text": {
                          "type": "string"
                        }
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "answers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AnswerFull"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/PromptNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/promptId"
          },
          {
            "$ref": "#/components/parameters/provider"
          }
        ]
      }
    },
    "/brands/{brandId}/search": {
      "get": {
        "tags": [
          "Search"
        ],
        "summary": "List query fan-outs",
        "description": "Returns aggregated web search queries generated by AI providers, grouped by query text.",
        "operationId": "listSearchInsights",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "searches": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SearchInsight"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/countries"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "occurrences",
                "priority",
                "brandPresence",
                "query",
                "createdAt"
              ],
              "default": "occurrences"
            }
          },
          {
            "$ref": "#/components/parameters/order"
          }
        ]
      }
    },
    "/brands/{brandId}/answers": {
      "get": {
        "tags": [
          "Answers"
        ],
        "summary": "List answers",
        "description": "Returns generated answers with filters. Countries and personas filter the immutable historical answer, independently of current prompt configuration.",
        "operationId": "listAnswers",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "answers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AnswerSummary"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/topic"
          },
          {
            "$ref": "#/components/parameters/tag"
          },
          {
            "$ref": "#/components/parameters/promptType"
          },
          {
            "name": "hasSelfMention",
            "in": "query",
            "description": "Filter by presence of brand mention",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "hasSelfSource",
            "in": "query",
            "description": "Filter by presence of brand source citation",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "createdAt"
              ],
              "default": "createdAt"
            }
          },
          {
            "$ref": "#/components/parameters/order"
          },
          {
            "$ref": "#/components/parameters/personaIds"
          },
          {
            "$ref": "#/components/parameters/countries"
          }
        ]
      }
    },
    "/brands/{brandId}/answers/{answerId}": {
      "get": {
        "tags": [
          "Answers"
        ],
        "summary": "Get answer details",
        "description": "Returns the complete response with full text and detailed analysis",
        "operationId": "getAnswer",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "answer": {
                      "$ref": "#/components/schemas/AnswerDetail"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/AnswerNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/answerId"
          }
        ]
      }
    },
    "/brands/{brandId}/keywords": {
      "get": {
        "tags": [
          "Keywords"
        ],
        "summary": "List keywords",
        "description": "Returns keyword/topic performance metrics with share of voice, mention rate, and sentiment.",
        "operationId": "listKeywords",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "keywords": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "keyword": {
                            "type": "string"
                          },
                          "totalPrompts": {
                            "type": "integer"
                          },
                          "totalAnswers": {
                            "type": "integer"
                          },
                          "brandMentionRate": {
                            "type": "number",
                            "description": "Percentage of answers mentioning SELF among answers mentioning SELF or DIRECT competitors."
                          },
                          "shareOfVoice": {
                            "type": "number",
                            "description": "Share of voice percentage (SELF / (SELF + DIRECT))"
                          },
                          "avgSentiment": {
                            "type": "number",
                            "description": "Average sentiment score (-100 to +100)"
                          }
                        }
                      }
                    },
                    "topics": {
                      "type": "array",
                      "description": "Present when view=configuration",
                      "items": {
                        "$ref": "#/components/schemas/TopicControl"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "name": "view",
            "in": "query",
            "description": "Use configuration to include topics without analytics and their versions",
            "schema": {
              "type": "string",
              "enum": [
                "analytics",
                "configuration"
              ],
              "default": "analytics"
            }
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/tag"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "prompts",
                "answers",
                "mentionRate",
                "shareOfVoice",
                "sentiment",
                "keyword"
              ],
              "default": "prompts"
            }
          },
          {
            "$ref": "#/components/parameters/order"
          }
        ]
      },
      "post": {
        "tags": [
          "Keywords"
        ],
        "summary": "Create a topic",
        "operationId": "createTopic",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 255
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Topic created",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "topic": {
                      "$ref": "#/components/schemas/TopicControl"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}/keywords/{keywordId}": {
      "get": {
        "tags": [
          "Keywords"
        ],
        "summary": "Get a topic configuration",
        "operationId": "getTopic",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/keywordId"
          }
        ],
        "responses": {
          "200": {
            "description": "Topic configuration",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "topic": {
                      "$ref": "#/components/schemas/TopicControl"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "description": "Get a topic configuration"
      },
      "patch": {
        "tags": [
          "Keywords"
        ],
        "summary": "Rename a topic",
        "operationId": "updateTopic",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/keywordId"
          },
          {
            "$ref": "#/components/parameters/ifMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Topic updated",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "topic": {
                      "$ref": "#/components/schemas/TopicControl"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      },
      "delete": {
        "tags": [
          "Keywords"
        ],
        "summary": "Delete a topic",
        "description": "Removes the topic label only. Prompts that carried it are detached and\nkeep their answers; nothing is deleted by cascade. Idempotent.\n",
        "operationId": "deleteTopic",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/keywordId"
          },
          {
            "$ref": "#/components/parameters/ifMatch"
          }
        ],
        "responses": {
          "200": {
            "description": "Topic deleted",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    },
                    "topicId": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}/keywords/{keywordId}/evolution": {
      "get": {
        "tags": [
          "Keywords"
        ],
        "summary": "Get keyword evolution",
        "description": "Returns daily time-series metrics for a specific keyword/topic.",
        "operationId": "getKeywordEvolution",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "keyword": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "text": {
                          "type": "string"
                        }
                      }
                    },
                    "evolution": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "date": {
                            "type": "string",
                            "format": "date"
                          },
                          "answers": {
                            "type": "integer"
                          },
                          "mentionRate": {
                            "type": "number"
                          },
                          "shareOfVoice": {
                            "type": "number"
                          },
                          "avgSentiment": {
                            "type": "number",
                            "nullable": true
                          },
                          "sourceRate": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Brand or keyword not found (BRAND_NOT_FOUND or KEYWORD_NOT_FOUND).",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "name": "keywordId",
            "in": "path",
            "required": true,
            "description": "The keyword ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/tag"
          },
          {
            "$ref": "#/components/parameters/promptType"
          }
        ]
      }
    },
    "/brands/{brandId}/tags": {
      "get": {
        "tags": [
          "Tags"
        ],
        "summary": "List tags",
        "description": "Returns tag performance metrics with share of voice, mention rate, and sentiment.",
        "operationId": "listTags",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "tags": {
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "totalPrompts": {
                                "type": "integer"
                              },
                              "totalAnswers": {
                                "type": "integer"
                              },
                              "brandMentionRate": {
                                "type": "number"
                              },
                              "shareOfVoice": {
                                "type": "number"
                              },
                              "avgSentiment": {
                                "type": "number"
                              }
                            }
                          },
                          {
                            "$ref": "#/components/schemas/TagControl"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "name": "view",
            "in": "query",
            "description": "Use configuration to include empty tags, colors and versions",
            "schema": {
              "type": "string",
              "enum": [
                "analytics",
                "configuration"
              ],
              "default": "analytics"
            }
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/topic"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "prompts",
                "answers",
                "mentionRate",
                "shareOfVoice",
                "sentiment",
                "name"
              ],
              "default": "prompts"
            }
          },
          {
            "$ref": "#/components/parameters/order"
          }
        ]
      },
      "post": {
        "tags": [
          "Tags"
        ],
        "summary": "Create a tag",
        "description": "Branded and Non-branded are reserved system tag names, whatever the\ncase. A request that uses one as the name returns 400 INVALID_REQUEST.\nIn a workspace created from v1.21, Qwairy creates these two tags\nitself and sets them on prompts from their text.\n",
        "operationId": "createTag",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "color": {
                    "type": "string",
                    "nullable": true,
                    "pattern": "^#[0-9a-fA-F]{6}$",
                    "description": "Hex color such as"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Tag created",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tag": {
                      "$ref": "#/components/schemas/TagControl"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}/tags/{tagId}": {
      "get": {
        "tags": [
          "Tags"
        ],
        "summary": "Get a tag configuration",
        "operationId": "getTag",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/tagId"
          }
        ],
        "responses": {
          "200": {
            "description": "Tag configuration",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "tag": {
                      "$ref": "#/components/schemas/TagControl"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "description": "Get a tag configuration"
      },
      "patch": {
        "tags": [
          "Tags"
        ],
        "summary": "Update a tag",
        "description": "Branded and Non-branded are reserved system tag names, whatever the\ncase. Renaming a tag to one of them, or updating one of the two system\ntags, returns 400 INVALID_REQUEST.\n",
        "operationId": "updateTag",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/tagId"
          },
          {
            "$ref": "#/components/parameters/ifMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "color": {
                    "type": "string",
                    "nullable": true,
                    "pattern": "^#[0-9a-fA-F]{6}$",
                    "description": "Hex color such as"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tag updated",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tag": {
                      "$ref": "#/components/schemas/TagControl"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      },
      "delete": {
        "tags": [
          "Tags"
        ],
        "summary": "Delete a tag",
        "description": "Removes the tag label only. Prompts are untagged and keep their answers.\nIdempotent. Deleting the Branded or Non-branded system tag returns 400\nINVALID_REQUEST.\n",
        "operationId": "deleteTag",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/tagId"
          },
          {
            "$ref": "#/components/parameters/ifMatch"
          }
        ],
        "responses": {
          "200": {
            "description": "Tag deleted",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    },
                    "tagId": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}/tags/{tagId}/evolution": {
      "get": {
        "tags": [
          "Tags"
        ],
        "summary": "Get tag evolution",
        "description": "Returns daily time-series metrics for a specific tag.",
        "operationId": "getTagEvolution",
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "tag": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        }
                      }
                    },
                    "evolution": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "date": {
                            "type": "string",
                            "format": "date"
                          },
                          "answers": {
                            "type": "integer"
                          },
                          "mentionRate": {
                            "type": "number"
                          },
                          "shareOfVoice": {
                            "type": "number"
                          },
                          "avgSentiment": {
                            "type": "number",
                            "nullable": true
                          },
                          "sourceRate": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Brand or tag not found (BRAND_NOT_FOUND or TAG_NOT_FOUND).",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "name": "tagId",
            "in": "path",
            "required": true,
            "description": "The tag ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/topic"
          },
          {
            "$ref": "#/components/parameters/promptType"
          }
        ]
      }
    },
    "/brands/{brandId}/monitoring": {
      "get": {
        "tags": [
          "Monitoring"
        ],
        "summary": "Get monitoring settings",
        "description": "Returns the effective monitoring configuration. This read never persists\nanything: when no settings are stored, computed defaults are returned\nwith isDefault set to true. Like the dashboard, those defaults select no\nmodel and do not generate answers automatically.\n",
        "operationId": "getMonitoring",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          }
        ],
        "responses": {
          "200": {
            "description": "Monitoring settings",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "monitoring": {
                      "$ref": "#/components/schemas/Monitoring"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "patch": {
        "tags": [
          "Monitoring"
        ],
        "summary": "Update monitoring settings",
        "description": "Updates the schedule and model selection. Set frequency to NONE to stop\nthe workspace schedule: prompts that inherit it stop, while prompts with\ntheir own frequency keep running, as in the dashboard. Per-prompt\nsettings are left untouched, so resuming restores the previous schedule\nexactly. Manual runs remain available, and work accepted before the\nchange may still finish.\n",
        "operationId": "updateMonitoring",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/ifMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "frequency": {
                    "type": "string",
                    "enum": [
                      "NONE",
                      "DAILY",
                      "WEEKLY",
                      "MONTHLY"
                    ]
                  },
                  "analysisWeekDay": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 7,
                    "nullable": true
                  },
                  "analysisMonthDay": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 28,
                    "nullable": true
                  },
                  "autoGenerateAnswers": {
                    "type": "boolean"
                  },
                  "models": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 20
                  },
                  "dryRun": {
                    "type": "boolean",
                    "default": false,
                    "description": "Validate and return the result without changing anything."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Monitoring updated",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "monitoring": {
                      "$ref": "#/components/schemas/Monitoring"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}/runs": {
      "get": {
        "tags": [
          "Runs"
        ],
        "summary": "List runs",
        "description": "Returns generation run summaries with computed status, outcome counts\nand progress, ordered by creation time descending and ID descending.\nPass nextCursor unchanged to retrieve the next page. totalCount and\nactiveCount cover all runs in the workspace, independent of the cursor.\nResponses use Cache-Control private, no-store so polling receives\ncurrent run activity.\n",
        "operationId": "listRuns",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque nextCursor from the preceding response; invalid cursors return 400",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Runs page",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "private, no-store"
                  ]
                }
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerationRunsPage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "post": {
        "tags": [
          "Runs"
        ],
        "summary": "Start a run",
        "description": "Starts a generation run and returns 202 with a Location pointing at the\nrun resource. The complete usable prompt/model scope is reserved and\nplanned atomically; insufficient credits or concurrent target changes\nreject the whole request. The Idempotency-Key replays the same response\nfor 24 hours. Reusing it after expiry starts new work. There is no\npublic cancel or retry endpoint.\nThe workspace must be LIVE and not locked. A request targets at most 50\nprompts: without promptIds, every prompt whose monitoring is enabled is\ntargeted, and more than 50 returns 400. Other refusals: 404 for an\nunknown prompt; 409 CONFLICT when no prompt is active, monitoring is\npaused on a requested prompt, no monitoring model is configured, some\nprompts target countries their models do not cover, or the targets\nchanged during planning; 409 INSUFFICIENT_CREDITS when the balance\ndoes not cover the run; 403 INSUFFICIENT_PLAN for an explicit premium\nmodel the plan does not include; 400 when none of the requested models\nis available.\n",
        "operationId": "startRun",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "promptIds": {
                    "type": "array",
                    "maxItems": 50,
                    "description": "Prompt IDs (UUIDs), at most 50. Omitted: every prompt of the\nworkspace whose monitoring is enabled, which returns 400\nwhen there are more than 50 of them.\n",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "modelIds": {
                    "type": "array",
                    "maxItems": 20,
                    "description": "Defaults to the workspace monitoring models",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Run accepted",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/StartedRun"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}/runs/estimate": {
      "post": {
        "tags": [
          "Runs"
        ],
        "summary": "Estimate a run",
        "description": "Prices a run without reserving or spending credits. It requires no\nIdempotency-Key and is subject to the standard write rate limit.\nIf every requested model is excluded, returns 200 with zero usable\nmodels, answers and estimated credits, plus unsupportedModels. Starting\nthat same run returns 400 until a usable model is selected.\nRequesting a premium model the plan does not include returns 403;\nstored premium selections the team can no longer use are skipped.\nTargets are resolved as in Start a run (a LIVE, unlocked workspace and\nat most 50 prompts) and refused with the same 400, 403, 404 and 409\nerrors, except those about usable models, credits and planning.\n",
        "operationId": "estimateRun",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "promptIds": {
                    "type": "array",
                    "maxItems": 50,
                    "description": "Same rule as Start a run",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "modelIds": {
                    "type": "array",
                    "maxItems": 20,
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Estimate",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "estimate": {
                      "$ref": "#/components/schemas/RunEstimate"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}/runs/{runId}": {
      "get": {
        "tags": [
          "Runs"
        ],
        "summary": "Get run details",
        "description": "Returns planning metadata and the number of recorded attempts for one\nrun, including whether planning completed or failed. Use the run\nsummaries from GET /brands/{brandId}/runs for computed status, outcome\ncounts and progressPercentage. This detail response names the prompt\ncount promptCount and uses Cache-Control private, no-store.\n",
        "operationId": "getRun",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "name": "runId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Run details",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "private, no-store"
                  ]
                }
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "run"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "run": {
                      "$ref": "#/components/schemas/RunDetail"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Workspace is not accessible, or the run was not found within the workspace",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RESOURCE_NOT_FOUND",
                    "message": "Run not found"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/pitch-audits": {
      "get": {
        "tags": [
          "Pitch Audits"
        ],
        "summary": "List Pitch Audits",
        "description": "Returns the Pitch Audits owned by the API key's agency team.",
        "operationId": "listPitchAudits",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "PENDING",
                "RUNNING",
                "RECOVERING",
                "AWAITING_PROMPTS",
                "COMPLETED",
                "FAILED"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Pitch Audit page",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "pagination",
                    "audits"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "audits": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PitchAuditListItem"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "post": {
        "tags": [
          "Pitch Audits"
        ],
        "summary": "Create a Pitch Audit",
        "description": "Creates and queues an agency Pitch Audit. Set autoStartResponses to\nfalse to review the generated prompts before starting billable answer\ncollection. The key must belong to an agency team on a write-enabled\nBusiness, Agency Business, or Enterprise plan.\nThe balance must cover the answers of the requested prompts and\nmodels even when autoStartResponses is false; otherwise the request\nreturns 409 INSUFFICIENT_CREDITS with requiredCredits and\navailableCredits.\n",
        "operationId": "createPitchAudit",
        "parameters": [
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "maxLength": 2048,
                    "description": "Prospect website URL or domain"
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "countryCode": {
                    "type": "string",
                    "default": "US",
                    "description": "Supported ISO 3166-1 alpha-2 market code"
                  },
                  "promptCount": {
                    "type": "integer",
                    "minimum": 20,
                    "maximum": 100,
                    "default": 30,
                    "description": "Number of prompts to prepare, from 20 to 100. With customPrompts, it must equal their number."
                  },
                  "customPrompts": {
                    "type": "array",
                    "minItems": 20,
                    "maxItems": 100,
                    "description": "From 20 to 100 distinct prompt texts imported instead of generated prompts.",
                    "items": {
                      "type": "string",
                      "maxLength": 1000
                    },
                    "uniqueItems": true
                  },
                  "modelIds": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 20,
                    "items": {
                      "type": "string"
                    }
                  },
                  "autoStartResponses": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Pitch Audit accepted",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "pitchAudit"
                  ],
                  "properties": {
                    "pitchAudit": {
                      "$ref": "#/components/schemas/PitchAuditCommandStatus"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/pitch-audits/{auditId}": {
      "get": {
        "tags": [
          "Pitch Audits"
        ],
        "summary": "Get a Pitch Audit",
        "description": "Returns progress or the original prospect report. Full answer text and\nco-competitor score expansion are opt-in to keep responses bounded.\n",
        "operationId": "getPitchAudit",
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "name": "includeAnswers",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "includeCoCompetitorScores",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pitch Audit report",
            "headers": {
              "ETag": {
                "description": "Current revision used to save a prompt-review draft. A compressed response can carry its weak form W/\"N\"; If-Match accepts both forms.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PitchAuditReportEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/PitchAuditNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/pitch-audits/{auditId}/reports/{subjectId}": {
      "get": {
        "tags": [
          "Pitch Audits"
        ],
        "summary": "Get a Pitch Audit subject report",
        "description": "Returns a competitor view derived from the same Pitch Audit evidence.",
        "operationId": "getPitchAuditSubjectReport",
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "$ref": "#/components/parameters/subjectId"
          },
          {
            "name": "includeAnswers",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "includeCoCompetitorScores",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pitch Audit subject report",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PitchAuditReportEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/PitchAuditNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/pitch-audits/{auditId}/prompts": {
      "patch": {
        "tags": [
          "Pitch Audits"
        ],
        "summary": "Save Pitch Audit prompts",
        "description": "Replaces the prompt-review draft while the audit is in\nAWAITING_PROMPTS. Use the ETag returned by Get Pitch Audit.\n",
        "operationId": "savePitchAuditPrompts",
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "$ref": "#/components/parameters/ifMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "prompts"
                ],
                "properties": {
                  "prompts": {
                    "type": "array",
                    "minItems": 20,
                    "maxItems": 100,
                    "items": {
                      "$ref": "#/components/schemas/PitchAuditPrompt"
                    },
                    "description": "From 20 to 100 prompts with unique ids. An unchanged draft created before this rule keeps its count."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Prompt-review draft saved",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "pitchAudit"
                  ],
                  "properties": {
                    "pitchAudit": {
                      "type": "object",
                      "required": [
                        "id",
                        "prompts",
                        "revision"
                      ],
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "prompts": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/PitchAuditPrompt"
                          }
                        },
                        "revision": {
                          "type": "integer",
                          "format": "int64"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/pitch-audits/{auditId}/confirm": {
      "post": {
        "tags": [
          "Pitch Audits"
        ],
        "summary": "Confirm Pitch Audit prompts",
        "description": "Confirms the saved or supplied prompts and queues billable answer\ncollection. The response reports the required and currently available\ncredits; completed answers are charged by the existing Pitch Audit\nbilling workflow. A concurrent audit edit returns 409 CONFLICT instead\nof overwriting the edit or preparing stale prompts. Re-read the audit\nand submit a new confirmation with a new Idempotency-Key after review.\n",
        "operationId": "confirmPitchAudit",
        "parameters": [
          {
            "$ref": "#/components/parameters/auditId"
          },
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompts": {
                    "type": "array",
                    "minItems": 20,
                    "maxItems": 100,
                    "items": {
                      "$ref": "#/components/schemas/PitchAuditPrompt"
                    },
                    "description": "From 20 to 100 prompts with unique ids. An unchanged draft created before this rule keeps its count."
                  },
                  "modelIds": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 20,
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Pitch Audit answer collection accepted",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "pitchAudit"
                  ],
                  "properties": {
                    "pitchAudit": {
                      "$ref": "#/components/schemas/PitchAuditCommandStatus"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/credits": {
      "get": {
        "tags": [
          "Credits"
        ],
        "summary": "Get credit overview",
        "description": "Balance, consumption over the last 30 days, runway and sub-team balances\nfor a parent organisation.\n",
        "operationId": "getCredits",
        "responses": {
          "200": {
            "description": "Credit overview",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "credits": {
                      "$ref": "#/components/schemas/Credits"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/actions": {
      "get": {
        "tags": [
          "Actions"
        ],
        "summary": "List Action Center recommendations",
        "description": "Returns recommendations ordered by stored priority descending, then\ncreation time descending. Without status, the live queue includes\nSUGGESTED, PENDING and IN_PROGRESS. Global filters match the evidence\nbehind recommendations. A period alone retains current site and brand\nrecommendations; dimension filters require matching evidence.\nNo recommendation generation is triggered by this read.\n",
        "operationId": "listActions",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ActionType"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Omit to return SUGGESTED, PENDING and IN_PROGRESS",
            "schema": {
              "$ref": "#/components/schemas/ActionStatus"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ActionCategory"
            }
          },
          {
            "name": "providers",
            "in": "query",
            "description": "Known AI provider IDs, comma-separated or repeated; a single all selects every provider",
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "maxItems": 20,
              "items": {
                "type": "string",
                "maxLength": 100
              }
            }
          },
          {
            "name": "topicIds",
            "in": "query",
            "description": "Topic UUIDs, comma-separated or repeated; a single all removes this filter",
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "maxItems": 100,
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "tagIds",
            "in": "query",
            "description": "Tag UUIDs, comma-separated or repeated; a single all removes this filter",
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "maxItems": 100,
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "tagOperator",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "or",
                "and"
              ],
              "default": "or"
            }
          },
          {
            "name": "funnelStages",
            "in": "query",
            "description": "TOFU, MOFU and/or BOFU, comma-separated or repeated; a single all removes this filter",
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "maxItems": 3,
              "items": {
                "type": "string",
                "enum": [
                  "TOFU",
                  "MOFU",
                  "BOFU",
                  "all"
                ]
              }
            }
          },
          {
            "name": "period",
            "in": "query",
            "description": "Evidence period; explicit bounds require custom",
            "schema": {
              "type": "string",
              "enum": [
                "1",
                "7",
                "14",
                "30",
                "90",
                "all",
                "custom"
              ],
              "default": "all"
            }
          },
          {
            "name": "periodStart",
            "in": "query",
            "description": "Inclusive UTC start date; required with period=custom and periodEnd. The range may span at most 3650 days.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "periodEnd",
            "in": "query",
            "description": "Inclusive UTC end date; required with period=custom and periodStart, and must not precede periodStart",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size; coerced to an integer and clamped to 1–100, with a fallback of 50",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number to skip; coerced to an integer and clamped to zero or greater",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recommendation queue",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid type, status, category or global filters",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Invalid Action Center filters"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/actions/{actionId}": {
      "patch": {
        "tags": [
          "Actions"
        ],
        "summary": "Update an action status",
        "operationId": "updateActionStatus",
        "x-qwairy-access": "api-write",
        "description": "Moves an Action Center recommendation to another status. Setting the\ncurrent status again is a no-op that returns the unchanged action.\nSUGGESTED and RESOLVED are assigned by Qwairy: moving an action to one of\nthem returns 409 INVALID_STATE_TRANSITION.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/actionId"
          },
          {
            "$ref": "#/components/parameters/ifMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "status"
                ],
                "properties": {
                  "status": {
                    "$ref": "#/components/schemas/ActionStatus"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated action",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionRecommendation"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}/site-diagnostics": {
      "get": {
        "tags": [
          "Site Diagnostics"
        ],
        "summary": "List monitored pages",
        "operationId": "listMonitoredPages",
        "x-qwairy-access": "api-read",
        "description": "Returns the pages Site Diagnostics monitors for a workspace, newest\nfirst, with their audit status, AI readiness score and open issue\ncount. Filter by audit status and paginate with limit and offset.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/PageAuditStatus"
            }
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Monitored pages",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MonitoredPageList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiPlanRequired"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/site-diagnostics/{pageId}": {
      "get": {
        "tags": [
          "Site Diagnostics"
        ],
        "summary": "Get a monitored page and its issues",
        "operationId": "getMonitoredPage",
        "x-qwairy-access": "api-read",
        "description": "Returns one monitored page with the technical and content issues\ndetected on it, the most severe first.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/pageId"
          }
        ],
        "responses": {
          "200": {
            "description": "Monitored page",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MonitoredPageDetail"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiPlanRequired"
          },
          "404": {
            "$ref": "#/components/responses/AnalyticsResourceNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/site-diagnostics/pages": {
      "post": {
        "tags": [
          "Site Diagnostics"
        ],
        "summary": "Add pages to monitor",
        "operationId": "addMonitoredPages",
        "x-qwairy-access": "api-write",
        "description": "Adds up to 50 URLs on the workspace domain, to a live workspace. URLs\nalready monitored are reported as already_monitored. Adding a page does\nnot audit it.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "urls"
                ],
                "properties": {
                  "urls": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 50,
                    "items": {
                      "type": "string",
                      "format": "uri",
                      "maxLength": 2048
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Per-URL outcome",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AddPagesResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}/site-diagnostics/audits": {
      "post": {
        "tags": [
          "Site Diagnostics"
        ],
        "summary": "Start a page audit",
        "operationId": "startSiteAudit",
        "x-qwairy-access": "api-write",
        "description": "Audits up to 50 monitored pages, or every monitored page with\nall=true. Returns 202 once the audit is accepted, with the audit and\nits id, and a Location header to poll, or subscribe an integration\nwebhook to the site_audit.completed event.\n202 means the request is recorded durably, not that every page is\nalready queued: if the queue cannot take the pages right away, the\naudit stays RUNNING and its pages are queued again automatically, with\nthe same keys, so a page is never queued nor debited twice. The audit\nis never deleted by a failure. Pages already being audited are\nreported as skipped in the audit detail, and pages that could not be\nqueued or audited as failed.\n\nQueueing the pages is retried up to 12 times, the first attempt\nincluded, and never later than 24 hours after the acceptance. An\nattempt interrupted before it records its outcome is not counted\ncomplete and can run again within those 24 hours, still with the\nsame keys. The pages the queue has not taken by then are FAILED. An\naudit with more than 100 pages to audit is returned without waiting\nfor queueing.\nIts pages are initially QUEUED; a background job running every five\nminutes queues them independently and may already have started when\nthe response arrives. The request itself only queues audits of 100\npages to audit or fewer.\n\nEach audited page uses 5 credits, debited page by page as each page\naudit starts, like an audit launched from the dashboard. The team\nbalance must cover every page to audit when the audit is accepted:\notherwise the request returns 409 INSUFFICIENT_CREDITS and starts\nnothing. If the balance is spent by someone else after the\nacceptance, the answer depends on how far the audit got. When no page\nstarted and the audit was queued during the request (100 pages to\naudit or fewer), the same 409 is returned with the audit id in its\ndetails: the audit is kept, with its pages FAILED. In every other\ncase, including an audit queued by the background job and an audit\nfor which some pages had already started, the response stays 202 with\nthe audit: the pages that could not start are FAILED, the pages\nalready started keep running, and the audit detail shows the outcome\nof each page. The workspace must be live. Use dryRun to get the pages\nand credits without starting the audit.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "pageIds": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 50,
                    "items": {
                      "type": "string"
                    }
                  },
                  "all": {
                    "type": "boolean",
                    "description": "Audit every monitored page. Mutually exclusive with pageIds."
                  },
                  "dryRun": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Dry run; nothing was started",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteAudit"
                }
              }
            }
          },
          "202": {
            "description": "Audit accepted",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteAudit"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}/site-diagnostics/audits/{siteAuditId}": {
      "get": {
        "tags": [
          "Site Diagnostics"
        ],
        "summary": "Get a page audit",
        "operationId": "getSiteAudit",
        "x-qwairy-access": "api-read",
        "description": "Returns the status of a page audit and of each page it covers: the\nresource the Location header of POST /site-diagnostics/audits points\nat. A page is QUEUED until its audit starts, then AUDITING, then\nCOMPLETED or FAILED. SKIPPED pages were not audited by this request.\nThe audit is COMPLETED once no page is QUEUED or AUDITING.\n\nThe status of a page is the result recorded for that page by the\naudit run that was queued for this audit, and only that run: another\naudit, the dashboard or a later analysis of the page never changes it.\nA page is COMPLETED when its run published its result, and FAILED when\nits run failed, was canceled, expired, or could not be queued or paid.\nA result is final: it never changes once recorded. A page whose run\nhas not started stays QUEUED, and a page whose run cannot exist\nanymore (queueing is retried up to 12 times within 24 hours, the\nqueued runs expire after 7 days) is FAILED. A run that is still active\non the queue is waited for. completedAt of a page is null while it is\nnot finished, and for a skipped page.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/siteAuditId"
          }
        ],
        "responses": {
          "200": {
            "description": "Audit status, per page",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteAudit"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiPlanRequired"
          },
          "404": {
            "$ref": "#/components/responses/AnalyticsResourceNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/content": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "List Content Studio articles",
        "description": "Returns article summaries, defaulting to LIVE articles. Retrieve the detail endpoint for Markdown content, metadata, outline and sources.",
        "operationId": "listContent",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "DRAFT",
                "GENERATING",
                "LIVE",
                "ARCHIVED"
              ],
              "default": "LIVE"
            }
          },
          {
            "name": "articleType",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ArticleType"
            }
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "createdAt",
                "updatedAt",
                "publishedAt",
                "title",
                "wordCount"
              ],
              "default": "updatedAt"
            }
          },
          {
            "$ref": "#/components/parameters/order"
          }
        ],
        "responses": {
          "200": {
            "description": "Article summaries",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/content/{articleId}": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "Get a Content Studio article",
        "description": "Returns a full article in any status, including its Markdown content, stored metadata, outline and ordered sources.",
        "operationId": "getContent",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "name": "articleId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full article",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "brand",
                    "article"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "brand": {
                      "$ref": "#/components/schemas/AnalyticsBrand"
                    },
                    "article": {
                      "$ref": "#/components/schemas/ContentArticleDetail"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/AnalyticsResourceNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/local": {
      "get": {
        "tags": [
          "Local"
        ],
        "summary": "List local business insights",
        "description": "Returns local businesses extracted from AI responses, filtered by\ninsight creation time. No date filter is applied by default. A period\ntakes precedence over a supplied startDate/endDate pair. A date pair\nincludes the entire end day. Numeric zero ratings, review counts and\npositions are serialized as null.\n",
        "operationId": "listLocal",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "name": "category",
            "in": "query",
            "description": "Case-insensitive substring of the business category",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "createdAt",
                "rating",
                "reviewCount",
                "position",
                "businessName"
              ],
              "default": "createdAt"
            }
          },
          {
            "$ref": "#/components/parameters/order"
          }
        ],
        "responses": {
          "200": {
            "description": "Local business recommendations",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LocalResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/matrix": {
      "get": {
        "tags": [
          "Matrix"
        ],
        "summary": "Get the GEO visibility matrix",
        "description": "Returns topic, tag, prompt or funnel rows with one cell per AI provider.\nRow overall metrics pool the underlying answers across providers.\nProvider averages are rounded arithmetic means of non-null cell metrics\nacross all matching rows. Summary and provider averages are computed\nbefore the row limit is applied; there is no offset pagination.\nAn explicit startDate/endDate pair overrides period. Dates use inclusive\nUTC boundaries; a timestamp start retains its exact instant, and a\ntimestamp end includes the remainder of its UTC day. Timestamps without\nan offset are interpreted as UTC.\n",
        "operationId": "getMatrix",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "name": "granularity",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "topics",
                "tags",
                "prompts",
                "funnel"
              ],
              "default": "topics"
            }
          },
          {
            "name": "period",
            "in": "query",
            "description": "1–3650 days, optionally suffixed with d, or 1W (7 days), 4W (28 days), 12W (84 days), YTD or all. custom requires startDate and endDate.",
            "schema": {
              "type": "string",
              "default": "30"
            }
          },
          {
            "name": "startDate",
            "in": "query",
            "description": "ISO 8601 date or timestamp; requires endDate and must not be later than it",
            "schema": {
              "type": "string",
              "example": "2026-08-01"
            }
          },
          {
            "name": "endDate",
            "in": "query",
            "description": "ISO 8601 date or timestamp; requires startDate",
            "schema": {
              "type": "string",
              "example": "2026-08-31"
            }
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/topic"
          },
          {
            "$ref": "#/components/parameters/tag"
          },
          {
            "name": "tagOperator",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "or",
                "and"
              ],
              "default": "or"
            }
          },
          {
            "name": "funnel",
            "in": "query",
            "description": "Comma-separated funnel stages",
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "TOFU",
                  "MOFU",
                  "BOFU"
                ]
              }
            }
          },
          {
            "name": "competitorDomainId",
            "in": "query",
            "description": "UUID of one live SELF competitor domain to use as the subject",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum returned rows; integer coercion and clamping to 1–100, with a fallback of 50",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Visibility matrix",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MatrixResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/perception": {
      "get": {
        "tags": [
          "Perception"
        ],
        "summary": "Get monthly brand perception",
        "description": "Returns completed monthly snapshots starting at the first day of the\noldest requested month (current month minus months plus one). Current and previous\nare the latest two available snapshots in that window. Trends subtract\nprevious from current scores; averages omit null values independently\nfor each score. History is ordered by year and month ascending.\n",
        "operationId": "getPerception",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "name": "months",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 24,
              "default": 12
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Perception scores and monthly history",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PerceptionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/perception/{snapshotId}": {
      "get": {
        "tags": [
          "Perception"
        ],
        "summary": "Get a completed perception snapshot",
        "description": "Returns the four scores, attribute alignment counts, SWOT insight titles and providers for one completed snapshot.",
        "operationId": "getPerceptionSnapshot",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "name": "snapshotId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Completed snapshot detail",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "brand",
                    "snapshot"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "brand": {
                      "$ref": "#/components/schemas/AnalyticsBrand"
                    },
                    "snapshot": {
                      "$ref": "#/components/schemas/PerceptionSnapshotDetail"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/AnalyticsResourceNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/prompts/{promptId}/evolution": {
      "get": {
        "tags": [
          "Prompts"
        ],
        "summary": "Get prompt evolution",
        "description": "Returns daily metrics in ascending date order, with no default date\nrestriction and no zero-filled dates. An explicit date pair overrides\nperiod. The tag filter restricts prompt eligibility; a prompt without\nany selected tag returns 404. Mention and source rates use eligible\nSELF/DIRECT answer denominators, rather than the total answers field.\n",
        "operationId": "getPromptEvolution",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/promptId"
          },
          {
            "name": "period",
            "in": "query",
            "description": "Number of days, clamped to 1–3650, or all for no date restriction",
            "schema": {
              "oneOf": [
                {
                  "type": "integer",
                  "minimum": 1
                },
                {
                  "type": "string",
                  "enum": [
                    "all"
                  ]
                }
              ]
            }
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/tag"
          }
        ],
        "responses": {
          "200": {
            "description": "Daily prompt metrics",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromptEvolution"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/PromptNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/shopping": {
      "get": {
        "tags": [
          "Shopping"
        ],
        "summary": "List shopping insights",
        "description": "Returns extracted product recommendations and normalized purchasing\noptions. Dates filter insight creation time; there is no default date\nrestriction. A period takes precedence over a supplied date pair.\nNumeric zero ratings and review counts are returned as null.\n",
        "operationId": "listShopping",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "createdAt",
                "rating",
                "reviews",
                "productName"
              ],
              "default": "createdAt"
            }
          },
          {
            "$ref": "#/components/parameters/order"
          }
        ],
        "responses": {
          "200": {
            "description": "Product recommendations",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShoppingResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/social": {
      "get": {
        "tags": [
          "Social"
        ],
        "summary": "List social citations",
        "description": "Returns citations classified as social or forum content, together with\ncitations from recognized social domains. Platform names remain reddit,\nyoutube, twitter, facebook, linkedin and other; additional recognized\nplatforms are returned as other. Dates filter citation creation time,\nwith no default restriction; an explicit date pair overrides period.\n",
        "operationId": "listSocial",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "name": "platform",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/SocialPlatform"
            }
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "createdAt",
                "position",
                "upvotes",
                "comments",
                "url"
              ],
              "default": "createdAt"
            }
          },
          {
            "$ref": "#/components/parameters/order"
          }
        ],
        "responses": {
          "200": {
            "description": "Social and forum citations",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SocialResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/source-urls": {
      "get": {
        "tags": [
          "Sources"
        ],
        "summary": "List source URLs",
        "description": "Returns citation metrics grouped by URL, title and domain, so the same\nURL can appear more than once when its title differs. Dates filter\nanswer creation time; an explicit date pair overrides period, and the\ndefault has no date restriction. Share of voice uses all citations\nmatching the same filters before pagination. Pagination total is read\nfrom returned rows and is 0 when the requested page is empty.\n",
        "operationId": "listSourceUrls",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/countries"
          },
          {
            "name": "domain",
            "in": "query",
            "description": "Exact source domain match",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "isSelf",
            "in": "query",
            "description": "Filter SELF citations, respecting the brand's configured host scope",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "isCompetitor",
            "in": "query",
            "description": "Filter citations linked to a DIRECT competitor",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "mentions",
                "position",
                "shareOfVoice",
                "url"
              ],
              "default": "mentions"
            }
          },
          {
            "$ref": "#/components/parameters/order"
          }
        ],
        "responses": {
          "200": {
            "description": "URL-level citation metrics",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceUrlsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/sponsored": {
      "get": {
        "tags": [
          "Sponsored"
        ],
        "summary": "List sponsored placements",
        "description": "Returns detected sponsored placements with decoded advertiser, product\nand description text. The response provider is a model ID. Dates filter\nplacement creation time, with no default restriction; a period takes\nprecedence over a supplied date pair.\n",
        "operationId": "listSponsored",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "name": "advertiser",
            "in": "query",
            "description": "Case-insensitive substring of the advertiser name",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "createdAt",
                "advertiserName",
                "productName",
                "position"
              ],
              "default": "createdAt"
            }
          },
          {
            "$ref": "#/components/parameters/order"
          }
        ],
        "responses": {
          "200": {
            "description": "Sponsored placements",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsoredResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/technical-analysis": {
      "get": {
        "tags": [
          "Technical Analysis"
        ],
        "summary": "Get stored technical analysis",
        "description": "Reads the latest stored robots.txt, llms.txt and sitemap.xml analyses\nand computes their AI Readiness score without starting a crawl. When\nno analysis exists, returns 200 with analyzed=false, null analyses and\na message. Opening AI Readiness in the app creates the initial analysis.\n",
        "operationId": "getTechnicalAnalysis",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          }
        ],
        "responses": {
          "200": {
            "description": "Stored analysis or an explicit not-yet-analyzed result",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TechnicalAnalysisResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/follow-ups": {
      "get": {
        "tags": [
          "Follow-Ups"
        ],
        "summary": "List Follow-Ups",
        "description": "Returns the next questions suggested after monitored AI answers, with their source prompt and provider provenance. Countries and personas filter the immutable historical source answer.",
        "operationId": "listFollowUps",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/period"
          },
          {
            "$ref": "#/components/parameters/startDate"
          },
          {
            "$ref": "#/components/parameters/endDate"
          },
          {
            "$ref": "#/components/parameters/provider"
          },
          {
            "$ref": "#/components/parameters/topic"
          },
          {
            "$ref": "#/components/parameters/tag"
          },
          {
            "$ref": "#/components/parameters/promptType"
          },
          {
            "$ref": "#/components/parameters/personaIds"
          },
          {
            "$ref": "#/components/parameters/countries"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "followUps": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "text",
                          "types",
                          "position",
                          "question",
                          "answer",
                          "isMonitored"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "text": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "SUGGESTION",
                              "GUIDED_CONTINUATION"
                            ],
                            "description": "SUGGESTION is a prompt the engine offers as is. GUIDED_CONTINUATION is the message ChatGPT sends once the user fills in the form it displays; its text names each form field as a {placeholder}."
                          },
                          "types": {
                            "type": "array",
                            "items": {
                              "$ref": "#/components/schemas/SignalType"
                            }
                          },
                          "position": {
                            "type": "integer"
                          },
                          "isMonitored": {
                            "type": "boolean"
                          },
                          "question": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "text": {
                                "type": "string"
                              }
                            }
                          },
                          "answer": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "providerId": {
                                "type": "string",
                                "nullable": true
                              },
                              "modelId": {
                                "type": "string"
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/webhooks": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "List webhook endpoints",
        "operationId": "listWebhookEndpoints",
        "x-qwairy-access": "webhooks",
        "description": "Endpoints of the team, oldest first. The signing secret is never returned.",
        "responses": {
          "200": {
            "description": "Endpoints of the team",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookEndpoint"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiPlanRequired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Create a webhook endpoint",
        "operationId": "createWebhookEndpoint",
        "x-qwairy-access": "webhooks",
        "description": "Creates an endpoint for the team. The signing secret is returned in\nthis response only; a retry with the same Idempotency-Key within 24\nhours returns this same response, secret included. At most 10\nendpoints per team (409 CONFLICT beyond). An unknown workspace in\nbrandIds returns 404.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEndpointCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Endpoint created",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointWithSecret"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/webhooks/{webhookId}": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Get a webhook endpoint",
        "operationId": "getWebhookEndpoint",
        "x-qwairy-access": "webhooks",
        "description": "One endpoint of the team. The signing secret is never returned.",
        "parameters": [
          {
            "$ref": "#/components/parameters/webhookId"
          }
        ],
        "responses": {
          "200": {
            "description": "Endpoint",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiPlanRequired"
          },
          "404": {
            "$ref": "#/components/responses/AnalyticsResourceNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "patch": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Update a webhook endpoint",
        "operationId": "updateWebhookEndpoint",
        "x-qwairy-access": "webhooks",
        "description": "Updates the URL, description, events, workspaces or activation.\nRe-enabling an endpoint disabled for failures clears its failure state.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/webhookId"
          },
          {
            "$ref": "#/components/parameters/ifMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEndpointUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated endpoint",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Delete a webhook endpoint",
        "operationId": "deleteWebhookEndpoint",
        "x-qwairy-access": "webhooks",
        "description": "Pending deliveries are cancelled. The delivery log stays readable for 30 days.",
        "parameters": [
          {
            "$ref": "#/components/parameters/webhookId"
          },
          {
            "$ref": "#/components/parameters/ifMatch"
          }
        ],
        "responses": {
          "204": {
            "description": "Endpoint deleted",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/webhooks/{webhookId}/rotate-secret": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Rotate the signing secret",
        "operationId": "rotateWebhookSecret",
        "x-qwairy-access": "webhooks",
        "description": "Returns the new secret in this response only; a retry with the same\nIdempotency-Key within 24 hours returns this same response. For 24\nhours, deliveries carry two signatures (new, then previous) so\nreceivers can switch without loss.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/webhookId"
          },
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Endpoint with its new secret",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointWithSecret"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/webhooks/{webhookId}/test": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Send a test event",
        "operationId": "sendWebhookTest",
        "x-qwairy-access": "webhooks",
        "description": "Queues a webhook.test event for this endpoint only, even when it is disabled.",
        "parameters": [
          {
            "$ref": "#/components/parameters/webhookId"
          },
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "responses": {
          "202": {
            "description": "Test delivery queued",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDelivery"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/webhooks/{webhookId}/deliveries": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "List deliveries",
        "operationId": "listWebhookDeliveries",
        "x-qwairy-access": "webhooks",
        "description": "Deliveries of the last 30 days, newest first.",
        "parameters": [
          {
            "$ref": "#/components/parameters/webhookId"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/WebhookDeliveryStatus"
            }
          },
          {
            "name": "event",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/WebhookEventType"
            }
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Deliveries",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookDelivery"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiPlanRequired"
          },
          "404": {
            "$ref": "#/components/responses/AnalyticsResourceNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Redeliver an event",
        "operationId": "redeliverWebhookDelivery",
        "x-qwairy-access": "webhooks",
        "description": "Queues the same event again for this endpoint, with the same event id,\nwhen the delivery is SUCCEEDED, EXHAUSTED or CANCELLED and less than\n30 days old. The endpoint must be enabled.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/webhookId"
          },
          {
            "$ref": "#/components/parameters/deliveryId"
          },
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "responses": {
          "202": {
            "description": "Delivery queued again",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDelivery"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}/prompt-suggestions": {
      "get": {
        "tags": [
          "Prompt Suggestions"
        ],
        "summary": "Get prompt suggestions",
        "description": "Returns the latest Prompt Studio generation for the workspace: the 20\nrecommendations first, then the rest of the scored pool, ordered for an\noptional funnel focus and cut at limit. The default limit of 20 returns\nthe recommendations; total gives the size of the whole pool. run is\nabsent and suggestions is empty when no generation exists yet.\nResponses use Cache-Control private, no-store.\n",
        "operationId": "getPromptSuggestions",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/focus"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of suggestions returned, recommendations first (default 20, max 500)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Suggestions",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "private, no-store"
                  ]
                }
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromptSuggestionList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiPlanRequired"
          },
          "404": {
            "$ref": "#/components/responses/BrandNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/prompt-suggestions/runs": {
      "post": {
        "tags": [
          "Prompt Suggestions"
        ],
        "summary": "Generate prompt suggestions",
        "description": "Starts a Prompt Studio generation for the workspace or for one topic.\nGeneration uses no customer credits. It is limited to 3 workspace\ngenerations and 10 topic generations per workspace over a rolling 24\nhours, and to 30 workspace generations and 60 topic generations per\nteam across all its workspaces, shared with the dashboard. At most one\nworkspace generation and one generation per topic can run at a time.\nA call beyond either allowance\nreturns 409 QUOTA_EXCEEDED with error.details.resetsAt when known;\na generation already running for the same scope returns 409 RESOURCE_BUSY\nwith error.details.suggestionRunId.\n\nThe generation is accepted once the call returns 202, and the Location\nheader points at it. A generation whose job could not be queued is\nreturned as FAILED and does not count toward the allowance: it is never\nreported as an error that would invite a second start.\n\nWith source manual, refill starts the generation of the one monitored\ntopic that needs suggestions most and returns that topic generation; it\nreturns 409 CONFLICT when no topic needs suggestions yet. With source\ntopic, a generation always adds to the current pool.\n",
        "operationId": "startPromptSuggestionRun",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "source": {
                    "type": "string",
                    "enum": [
                      "manual",
                      "topic"
                    ],
                    "default": "manual"
                  },
                  "keywordId": {
                    "type": "string",
                    "description": "Required when source is topic, refused otherwise."
                  },
                  "refill": {
                    "type": "boolean",
                    "default": false,
                    "description": "Adds suggestions to the current pool instead of starting over."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Generation accepted",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromptSuggestionRun"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    },
    "/brands/{brandId}/prompt-suggestions/runs/{suggestionRunId}": {
      "get": {
        "tags": [
          "Prompt Suggestions"
        ],
        "summary": "Get a suggestion generation",
        "description": "Returns the status of one generation: the resource the Location header\nof a start points at. Only the public status is returned, never the\nworking state, the result or an internal error.\n",
        "operationId": "getPromptSuggestionRun",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/suggestionRunId"
          }
        ],
        "responses": {
          "200": {
            "description": "Generation status",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "private, no-store"
                  ]
                }
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromptSuggestionRun"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ApiPlanRequired"
          },
          "404": {
            "$ref": "#/components/responses/AnalyticsResourceNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/brands/{brandId}/prompt-suggestions/accept": {
      "post": {
        "tags": [
          "Prompt Suggestions"
        ],
        "summary": "Accept prompt suggestions",
        "description": "Creates prompts from up to 20 suggestions of the latest generation,\nthrough the import the dashboard Studio uses. Accepted prompts are\nmonitored by default, which adds a recurring credit consumption\nreported in dailyCredits. Use dryRun to preview the outcomes and that\nconsumption without creating anything.\n\nReturns 200 with an outcome for every suggestion: created,\nalready_tracked, not_found or invalid. Inspect every item, the status\nalone does not mean every suggestion was accepted. In a workspace\ncreated from v1.21, each created prompt also carries the Branded or\nNon-branded system tag; a workspace created earlier has none.\n\nAccepting starts no collection itself, but on a LIVE workspace it can\nmake monitored prompts due at the next scheduler pass, which runs on\nthe hour and the half hour (UTC): a new prompt when automatic answers\nare on, or a reactivated prompt whose last collection is older than\nits frequency. That first collection uses credits once, on top of\ndailyCredits. This response, dryRun included, does not report that\namount; the preview of the accept_prompt_suggestions MCP tool does.\n\nA suggestion equivalent to an archived or paused prompt reactivates\nthat prompt and reports created, as in the dashboard Studio: the\nimport rewrites its text, funnel stage and topic, clears its\ncountries and resets its personas and models to the workspace\ndefaults.\n",
        "operationId": "acceptPromptSuggestions",
        "parameters": [
          {
            "$ref": "#/components/parameters/brandId"
          },
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "suggestionIds"
                ],
                "properties": {
                  "suggestionIds": {
                    "type": "array",
                    "description": "Opaque IDs returned by the latest suggestions read. IDs bind to content and taxonomy; a replaced suggestion returns not_found instead of accepting different content.",
                    "minItems": 1,
                    "maxItems": 20,
                    "uniqueItems": true,
                    "items": {
                      "type": "string",
                      "maxLength": 200
                    }
                  },
                  "keywordId": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true,
                    "description": "Topic for every accepted prompt. Omit it to use the suggested topic of each prompt; null for no topic."
                  },
                  "tagIds": {
                    "type": "array",
                    "maxItems": 20,
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "monitoringEnabled": {
                    "type": "boolean",
                    "default": true
                  },
                  "dryRun": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Per-suggestion outcome",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitBurstLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitBurstRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitBurstReset"
              },
              "X-RateLimit-Daily-Limit": {
                "$ref": "#/components/headers/RateLimitDailyLimit"
              },
              "X-RateLimit-Daily-Remaining": {
                "$ref": "#/components/headers/RateLimitDailyRemaining"
              },
              "X-RateLimit-Daily-Reset": {
                "$ref": "#/components/headers/RateLimitDailyReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AcceptSuggestionsResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WriteInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/WriteUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/WriteForbidden"
          },
          "404": {
            "$ref": "#/components/responses/WriteNotFound"
          },
          "409": {
            "$ref": "#/components/responses/WriteConflict"
          },
          "413": {
            "$ref": "#/components/responses/WriteRequestTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/WriteRateLimited"
          },
          "500": {
            "$ref": "#/components/responses/WriteInternalError"
          },
          "503": {
            "$ref": "#/components/responses/WriteUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Token",
        "description": "API token with qw-api- prefix"
      }
    },
    "parameters": {
      "brandId": {
        "name": "brandId",
        "in": "path",
        "required": true,
        "description": "The unique identifier of the brand",
        "schema": {
          "type": "string"
        }
      },
      "keywordId": {
        "name": "keywordId",
        "in": "path",
        "required": true,
        "description": "The topic identifier",
        "schema": {
          "type": "string"
        }
      },
      "tagId": {
        "name": "tagId",
        "in": "path",
        "required": true,
        "description": "The tag identifier",
        "schema": {
          "type": "string"
        }
      },
      "auditId": {
        "name": "auditId",
        "in": "path",
        "required": true,
        "description": "Pitch Audit identifier",
        "schema": {
          "type": "string"
        }
      },
      "subjectId": {
        "name": "subjectId",
        "in": "path",
        "required": true,
        "description": "Competitor report subject identifier returned by the parent report",
        "schema": {
          "type": "string",
          "maxLength": 160
        }
      },
      "idempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "Unique key for this logical request. Replaying it with the same body for\n24 hours returns the original response; reusing it with a different body\nreturns 409.\n",
        "schema": {
          "type": "string",
          "maxLength": 255
        }
      },
      "ifMatch": {
        "name": "If-Match",
        "in": "header",
        "required": true,
        "description": "The ETag you last read for this resource. Use `*` to write\nunconditionally. The strong form (\"7\") and the weak form (W/\"7\") are\nboth accepted and pin the same version. Missing returns 428, stale\nreturns 412.\n",
        "schema": {
          "type": "string"
        }
      },
      "focus": {
        "name": "focus",
        "in": "query",
        "required": false,
        "description": "Funnel focus that orders the recommendations",
        "schema": {
          "type": "string",
          "enum": [
            "balanced",
            "DISCOVERY",
            "CONSIDERATION",
            "PERCEPTION",
            "AUTHORITY"
          ],
          "default": "balanced"
        }
      },
      "suggestionRunId": {
        "name": "suggestionRunId",
        "in": "path",
        "required": true,
        "description": "Generation identifier returned when the generation started",
        "schema": {
          "type": "string"
        }
      },
      "competitorId": {
        "name": "competitorId",
        "in": "path",
        "required": true,
        "description": "The unique identifier of the competitor",
        "schema": {
          "type": "string"
        }
      },
      "sourceId": {
        "name": "sourceId",
        "in": "path",
        "required": true,
        "description": "The unique identifier of the source",
        "schema": {
          "type": "string"
        }
      },
      "promptId": {
        "name": "promptId",
        "in": "path",
        "required": true,
        "description": "The unique identifier of the prompt",
        "schema": {
          "type": "string"
        }
      },
      "answerId": {
        "name": "answerId",
        "in": "path",
        "required": true,
        "description": "The unique identifier of the answer",
        "schema": {
          "type": "string"
        }
      },
      "period": {
        "name": "period",
        "in": "query",
        "description": "Number of days to include. No default; returns all data if neither period nor a complete date range is specified. SQL-based date filters cap this at 3650 days. Avoid combining period with a date range; precedence varies by operation.",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "startDate": {
        "name": "startDate",
        "in": "query",
        "description": "Start date or timestamp in ISO 8601 format; used with endDate",
        "schema": {
          "type": "string"
        }
      },
      "endDate": {
        "name": "endDate",
        "in": "query",
        "description": "End date or timestamp in ISO 8601 format; used with startDate. Analytics date pairs include the end day.",
        "schema": {
          "type": "string"
        }
      },
      "provider": {
        "name": "provider",
        "in": "query",
        "description": "Filter by AI provider. Supports comma-separated values for multi-select (e.g., \"chatgpt,claude\").",
        "schema": {
          "type": "string",
          "example": "chatgpt,claude"
        }
      },
      "topic": {
        "name": "topic",
        "in": "query",
        "description": "Filter by topic (keyword) ID. Supports comma-separated values for multi-select (e.g., \"id1,id2\").",
        "schema": {
          "type": "string"
        }
      },
      "tag": {
        "name": "tag",
        "in": "query",
        "description": "Filter by tag ID. Supports comma-separated values for multi-select (e.g., \"id1,id2\").",
        "schema": {
          "type": "string"
        }
      },
      "promptType": {
        "name": "type",
        "in": "query",
        "description": "Filter by prompt type (funnel stage)",
        "schema": {
          "type": "string",
          "enum": [
            "TOFU",
            "MOFU",
            "BOFU",
            "POST_PURCHASE"
          ]
        }
      },
      "limit": {
        "name": "limit",
        "in": "query",
        "description": "Maximum number of results (default 50, max 100)",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 50
        }
      },
      "offset": {
        "name": "offset",
        "in": "query",
        "description": "Number of results to skip for pagination",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "default": 0
        }
      },
      "order": {
        "name": "order",
        "in": "query",
        "description": "Sort order",
        "schema": {
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ],
          "default": "desc"
        }
      },
      "personaIds": {
        "name": "personaIds",
        "in": "query",
        "description": "Filter by comma-separated persona UUIDs. On /prompts this matches current configured personas; `default` means no QuestionPersona association. On /answers and /follow-ups this matches the historical answer persona; `default` means an answer generated without a persona.",
        "schema": {
          "type": "string",
          "example": "11111111-1111-4111-8111-111111111111,default"
        }
      },
      "countries": {
        "name": "countries",
        "in": "query",
        "description": "Filter /answers, /follow-ups or /search by the immutable historical Answer.countryCode snapshot, and /source-domains or /source-urls by that snapshot of the citing answer. Accepts up to 50 comma-separated ISO 3166-1 alpha-2 entries before deduplication. Entries are trimmed, uppercased and deduplicated; any invalid entry returns HTTP 400. An absent or empty value applies no filter. A valid country without data returns no results.",
        "schema": {
          "type": "string",
          "example": "FR,BE"
        }
      },
      "configuredCountries": {
        "name": "countries",
        "in": "query",
        "description": "Filter /prompts by effective currently configured countries, not historical answers. Prompt countries are intersected with the current workspace country catalog; an empty or entirely obsolete configuration falls back to the workspace default country. Answer metrics are not scoped by country. Accepts up to 50 comma-separated ISO 3166-1 alpha-2 entries before deduplication. Entries are trimmed, uppercased and deduplicated; any invalid entry returns HTTP 400. An absent or empty value applies no filter. A valid country without matching configuration returns no results.",
        "schema": {
          "type": "string",
          "example": "FR,BE"
        }
      },
      "actionId": {
        "name": "actionId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "pageId": {
        "name": "pageId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "siteAuditId": {
        "name": "siteAuditId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "webhookId": {
        "name": "webhookId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "deliveryId": {
        "name": "deliveryId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "AnalyticsBrand": {
        "type": "object",
        "required": [
          "id",
          "name",
          "domain"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "domain": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "ReadPaginatedResponse": {
        "type": "object",
        "required": [
          "success",
          "pagination"
        ],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "ActionType": {
        "type": "string",
        "enum": [
          "CONTENT_GAP",
          "CONTENT_OPTIMIZE",
          "TECHNICAL_FIX",
          "SCHEMA_ADD",
          "AUTHORITY_BUILD",
          "SOURCE_OUTREACH",
          "COMPETITOR_ANALYSIS",
          "PERCEPTION_FIX",
          "SEARCH_TARGET",
          "SOCIAL_ENGAGE",
          "PRODUCT_OPTIMIZE",
          "LOCAL_OPTIMIZE"
        ]
      },
      "ActionStatus": {
        "type": "string",
        "enum": [
          "SUGGESTED",
          "PENDING",
          "IN_PROGRESS",
          "COMPLETED",
          "DISMISSED",
          "RESOLVED"
        ]
      },
      "ActionCategory": {
        "type": "string",
        "enum": [
          "TECHNICAL",
          "CONTENT",
          "AEO",
          "AUTHORITY",
          "VISIBILITY"
        ]
      },
      "ActionsResponse": {
        "type": "object",
        "required": [
          "data",
          "pagination"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ActionRecommendation"
            }
          },
          "pagination": {
            "type": "object",
            "required": [
              "total",
              "limit",
              "offset",
              "hasMore"
            ],
            "properties": {
              "total": {
                "type": "integer"
              },
              "limit": {
                "type": "integer"
              },
              "offset": {
                "type": "integer"
              },
              "hasMore": {
                "type": "boolean",
                "description": "True when offset plus returned row count is less than total"
              }
            }
          }
        }
      },
      "ActionRecommendation": {
        "type": "object",
        "required": [
          "id",
          "type",
          "category",
          "sourceType",
          "scope",
          "title",
          "description",
          "sourceUrl",
          "targetProvider",
          "evidenceProviders",
          "evidenceScope",
          "forceTier",
          "priorityScore",
          "demandBadge",
          "isQuickWin",
          "effort",
          "status",
          "signals",
          "impactJustification",
          "effortJustification",
          "baselineMetric",
          "targetMetric",
          "questionId",
          "checklist",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "$ref": "#/components/schemas/ActionType"
          },
          "category": {
            "$ref": "#/components/schemas/ActionCategory"
          },
          "sourceType": {
            "type": "string",
            "enum": [
              "PAGE_ISSUE",
              "QUESTION_GAP",
              "COMPETITOR_GAP",
              "PERCEPTION_GAP",
              "SOURCE_OPPORTUNITY",
              "TECHNICAL_AUDIT",
              "CONTENT_OPPORTUNITY",
              "SEARCH_QUERY",
              "SOCIAL_CITATION",
              "SHOPPING_GAP",
              "LOCAL_GAP",
              "ONBOARDING"
            ]
          },
          "scope": {
            "type": "string",
            "enum": [
              "ON_SITE",
              "OFF_SITE",
              "SETUP"
            ]
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "sourceUrl": {
            "type": "string",
            "nullable": true
          },
          "targetProvider": {
            "type": "string",
            "nullable": true,
            "description": "Provider the recommendation is intended to improve"
          },
          "evidenceProviders": {
            "type": "array",
            "description": "Sorted, deduplicated known providers present in the underlying evidence",
            "items": {
              "type": "string"
            }
          },
          "evidenceScope": {
            "type": "string",
            "enum": [
              "OBSERVED",
              "CURRENT",
              "UNATTRIBUTED"
            ]
          },
          "forceTier": {
            "type": "string",
            "enum": [
              "CRITICAL",
              "HIGH",
              "STANDARD"
            ]
          },
          "priorityScore": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Rounded tier base (70 CRITICAL, 40 HIGH, 10 STANDARD) plus demand\n((clamped demandBadge - 1) / 4 * 18), effort bonus (8 LOW, 4 MEDIUM,\n0 HIGH), and 4 when targetProvider is set. Capped at 100, 69 or 39\nrespectively. Derived on read; the queue orders by stored priority.\n"
          },
          "demandBadge": {
            "type": "integer",
            "description": "Demand signal on a 1–5 scale"
          },
          "isQuickWin": {
            "type": "boolean"
          },
          "effort": {
            "type": "string",
            "enum": [
              "LOW",
              "MEDIUM",
              "HIGH"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/ActionStatus"
          },
          "signals": {
            "$ref": "#/components/schemas/ActionSignals"
          },
          "impactJustification": {
            "type": "string",
            "nullable": true
          },
          "effortJustification": {
            "type": "string",
            "nullable": true
          },
          "baselineMetric": {
            "type": "number",
            "nullable": true,
            "description": "Initial value of the action's measured outcome; units depend on the recommendation"
          },
          "targetMetric": {
            "type": "number",
            "nullable": true,
            "description": "Target value in the same units as baselineMetric"
          },
          "questionId": {
            "type": "string",
            "nullable": true
          },
          "checklist": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "version": {
            "type": "integer",
            "description": "Send as If-Match, in quotes (`\"7\"`), to change the status."
          }
        }
      },
      "ActionSignals": {
        "type": "object",
        "nullable": true,
        "description": "Stored detector evidence. Fields vary by recommendation family; additional evidence fields may be present.",
        "additionalProperties": true,
        "properties": {
          "severity": {
            "type": "string",
            "enum": [
              "CRITICAL",
              "HIGH",
              "MEDIUM",
              "LOW"
            ]
          },
          "visibilityPotential": {
            "type": "number"
          },
          "competitorAdvantage": {
            "type": "number"
          },
          "trafficPotential": {
            "type": "number"
          },
          "brandMentionGap": {
            "type": "boolean"
          },
          "impressions": {
            "type": "number"
          },
          "position": {
            "type": "number"
          },
          "citations": {
            "type": "number"
          },
          "fanoutOccurrences": {
            "type": "number"
          },
          "signalWindow": {
            "type": "string",
            "enum": [
              "recent_30d",
              "all_time",
              "all_time_fallback"
            ]
          },
          "competitivePressure": {
            "type": "number"
          },
          "competitors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "providers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "providerEvidenceVersion": {
            "type": "integer"
          },
          "providerEvidence": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "provider": {
                  "type": "string"
                },
                "observedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "questionId": {
                  "type": "string"
                },
                "evidenceId": {
                  "type": "string"
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "WEB_SEARCH_QUERY",
                    "SOURCE_MENTION",
                    "SHOPPING_INSIGHT",
                    "LOCAL_BUSINESS"
                  ]
                }
              }
            }
          },
          "pages": {
            "type": "number"
          },
          "sourceCategory": {
            "type": "string"
          },
          "sourceVerification": {
            "type": "string",
            "enum": [
              "VERIFIED_ABSENT",
              "UNKNOWN"
            ]
          },
          "domainRating": {
            "type": "number"
          },
          "sourceAuthorityScore": {
            "type": "number"
          },
          "sourceAuthorityConfidence": {
            "type": "number"
          },
          "price": {
            "type": "number"
          },
          "backlinkBudget": {
            "type": "number"
          },
          "citedPublishers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "citedSocial": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "routeHint": {
            "type": "string",
            "enum": [
              "OUTREACH",
              "SOCIAL",
              "CONTENT"
            ]
          },
          "lowValue": {
            "type": "boolean"
          },
          "lowValueReason": {
            "type": "string"
          }
        }
      },
      "ArticleType": {
        "type": "string",
        "enum": [
          "INFORMATIONAL",
          "COMPARISON",
          "HOW_TO",
          "LISTICLE",
          "REVIEW",
          "CASE_STUDY",
          "NEWS",
          "OPINION",
          "OTHER"
        ]
      },
      "ContentListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ReadPaginatedResponse"
          },
          {
            "type": "object",
            "required": [
              "articles"
            ],
            "properties": {
              "articles": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ContentArticle"
                }
              }
            }
          }
        ]
      },
      "ContentArticle": {
        "type": "object",
        "required": [
          "id",
          "title",
          "slug",
          "description",
          "articleType",
          "status",
          "wordCount",
          "finalUrl",
          "publishedAt",
          "generatedAt",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "slug": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "articleType": {
            "$ref": "#/components/schemas/ArticleType"
          },
          "status": {
            "type": "string",
            "enum": [
              "DRAFT",
              "GENERATING",
              "LIVE",
              "ARCHIVED"
            ]
          },
          "wordCount": {
            "type": "integer"
          },
          "finalUrl": {
            "type": "string",
            "nullable": true
          },
          "publishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ContentArticleDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ContentArticle"
          },
          {
            "type": "object",
            "required": [
              "content",
              "targetLength",
              "guidelines",
              "includeTldr",
              "includeFaq",
              "metaData",
              "outline",
              "sources"
            ],
            "properties": {
              "content": {
                "type": "string",
                "description": "Full Markdown article content; may be empty before generation"
              },
              "targetLength": {
                "type": "integer",
                "description": "Requested word count"
              },
              "guidelines": {
                "type": "string",
                "nullable": true
              },
              "includeTldr": {
                "type": "boolean"
              },
              "includeFaq": {
                "type": "boolean"
              },
              "metaData": {
                "$ref": "#/components/schemas/ArticleMetadata"
              },
              "outline": {
                "$ref": "#/components/schemas/ArticleOutline"
              },
              "sources": {
                "type": "array",
                "description": "Sources ordered by order ascending",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "title",
                    "url",
                    "usageType",
                    "order"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string",
                      "nullable": true
                    },
                    "url": {
                      "type": "string"
                    },
                    "usageType": {
                      "type": "string",
                      "enum": [
                        "AUTO",
                        "COMPETITOR",
                        "AUTHORITY",
                        "INSPIRATION",
                        "REFERENCE"
                      ]
                    },
                    "order": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "ArticleMetadata": {
        "description": "Stored JSON returned without normalization, or null. Object values can contain the generated metadata fields below; legacy or edited JSON may have a different shape.",
        "properties": {
          "metaTitle": {
            "type": "string"
          },
          "metaDescription": {
            "type": "string"
          },
          "focusKeywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "slug": {
            "type": "string"
          },
          "languageCode": {
            "type": "string"
          },
          "openGraph": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "type": {
                "type": "string"
              }
            }
          },
          "twitter": {
            "type": "object",
            "properties": {
              "card": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "description": {
                "type": "string"
              }
            }
          },
          "faqSchema": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "question": {
                  "type": "string"
                },
                "answer": {
                  "type": "string"
                }
              }
            }
          },
          "articleSchema": {
            "type": "object",
            "properties": {
              "headline": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "keywords": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "articleSection": {
                "type": "string"
              },
              "wordCount": {
                "type": "number"
              }
            }
          }
        }
      },
      "ArticleOutline": {
        "description": "Stored JSON returned without normalization, or null. Generated outlines use sections; legacy or edited JSON may have a different shape.",
        "properties": {
          "sections": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "level": {
                  "type": "number"
                },
                "title": {
                  "type": "string"
                },
                "order": {
                  "type": "number"
                },
                "estimatedWords": {
                  "type": "number",
                  "description": "Optional field retained in legacy outlines"
                }
              }
            }
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "LocalResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ReadPaginatedResponse"
          },
          {
            "type": "object",
            "required": [
              "local"
            ],
            "properties": {
              "local": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/LocalBusiness"
                }
              }
            }
          }
        ]
      },
      "LocalBusiness": {
        "type": "object",
        "required": [
          "id",
          "businessName",
          "category",
          "address",
          "websiteUrl",
          "position",
          "rating",
          "reviewCount",
          "prompt",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "businessName": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "nullable": true
          },
          "address": {
            "type": "string",
            "nullable": true
          },
          "websiteUrl": {
            "type": "string",
            "nullable": true
          },
          "position": {
            "type": "integer",
            "nullable": true
          },
          "rating": {
            "type": "number",
            "nullable": true
          },
          "reviewCount": {
            "type": "integer",
            "nullable": true
          },
          "prompt": {
            "type": "string",
            "nullable": true,
            "description": "Originating prompt text"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ShoppingResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ReadPaginatedResponse"
          },
          {
            "type": "object",
            "required": [
              "shopping"
            ],
            "properties": {
              "shopping": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ShoppingInsight"
                }
              }
            }
          }
        ]
      },
      "ShoppingInsight": {
        "type": "object",
        "required": [
          "id",
          "productName",
          "description",
          "image",
          "rating",
          "reviews",
          "options",
          "prompt",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "productName": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "image": {
            "type": "string",
            "nullable": true
          },
          "rating": {
            "type": "number",
            "nullable": true
          },
          "reviews": {
            "type": "integer",
            "nullable": true
          },
          "options": {
            "type": "array",
            "description": "Stored normalized purchasing options; an absent value is returned as an empty array",
            "items": {
              "$ref": "#/components/schemas/ShoppingOption"
            }
          },
          "prompt": {
            "type": "string",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ShoppingOption": {
        "type": "object",
        "properties": {
          "price": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "currency": {
            "type": "string"
          },
          "websiteName": {
            "type": "string",
            "nullable": true
          },
          "websiteUrl": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "SocialPlatform": {
        "type": "string",
        "enum": [
          "reddit",
          "youtube",
          "twitter",
          "facebook",
          "linkedin",
          "other"
        ]
      },
      "SocialResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ReadPaginatedResponse"
          },
          {
            "type": "object",
            "required": [
              "social"
            ],
            "properties": {
              "social": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/SocialCitation"
                }
              }
            }
          }
        ]
      },
      "SocialCitation": {
        "type": "object",
        "required": [
          "id",
          "platform",
          "communityId",
          "communityName",
          "url",
          "title",
          "domain",
          "position",
          "upvotes",
          "commentCount",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Source citation identifier"
          },
          "platform": {
            "$ref": "#/components/schemas/SocialPlatform"
          },
          "communityId": {
            "type": "string",
            "nullable": true
          },
          "communityName": {
            "type": "string",
            "nullable": true
          },
          "url": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "domain": {
            "type": "string"
          },
          "position": {
            "type": "integer",
            "nullable": true,
            "description": "Citation position; a numeric zero is returned as null"
          },
          "upvotes": {
            "type": "integer",
            "description": "upvotes or score from source metadata; defaults to zero"
          },
          "commentCount": {
            "type": "integer",
            "description": "comments or num_comments from source metadata; defaults to zero"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SourceUrlsResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ReadPaginatedResponse"
          },
          {
            "type": "object",
            "required": [
              "sourceUrls"
            ],
            "properties": {
              "sourceUrls": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/SourceUrl"
                }
              }
            }
          }
        ]
      },
      "SourceUrl": {
        "type": "object",
        "required": [
          "url",
          "title",
          "domain",
          "isSelf",
          "isCompetitor",
          "competitors",
          "totalMentions",
          "avgPosition",
          "shareOfVoice",
          "topics",
          "tags"
        ],
        "properties": {
          "url": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "domain": {
            "type": "string"
          },
          "isSelf": {
            "type": "boolean",
            "nullable": true,
            "description": "True for a matching SELF domain and configured host scope; can be null when no relationship is known"
          },
          "isCompetitor": {
            "type": "boolean",
            "nullable": true,
            "description": "True for a DIRECT competitor; can be null when no relationship is known"
          },
          "competitors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "totalMentions": {
            "type": "integer",
            "description": "Citation count for this URL, title and domain group"
          },
          "avgPosition": {
            "type": "number",
            "nullable": true,
            "description": "Mean citation position rounded to two decimals; zero is serialized as null"
          },
          "shareOfVoice": {
            "type": "number",
            "description": "Group citation count / all filtered citation counts * 100, rounded to two decimals"
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "text"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "text": {
                  "type": "string"
                }
              }
            }
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "name"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "SponsoredResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ReadPaginatedResponse"
          },
          {
            "type": "object",
            "required": [
              "sponsored"
            ],
            "properties": {
              "sponsored": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/SponsoredPlacement"
                }
              }
            }
          }
        ]
      },
      "SponsoredPlacement": {
        "type": "object",
        "required": [
          "id",
          "advertiserName",
          "advertiserLogo",
          "productName",
          "description",
          "imageUrl",
          "position",
          "provider",
          "competitorRelationship",
          "prompt",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "advertiserName": {
            "type": "string"
          },
          "advertiserLogo": {
            "type": "string",
            "nullable": true
          },
          "productName": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "imageUrl": {
            "type": "string",
            "nullable": true
          },
          "position": {
            "type": "integer"
          },
          "provider": {
            "type": "string",
            "description": "Stored AI model ID"
          },
          "competitorRelationship": {
            "type": "string",
            "nullable": true,
            "description": "Relationship of the linked competitor domain, if any"
          },
          "prompt": {
            "type": "string",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MatrixResponse": {
        "type": "object",
        "required": [
          "success",
          "brand",
          "granularity",
          "providers",
          "rows",
          "providerAverages",
          "summary"
        ],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "brand": {
            "type": "object",
            "required": [
              "id",
              "name"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "granularity": {
            "type": "string",
            "enum": [
              "topics",
              "tags",
              "prompts",
              "funnel"
            ]
          },
          "providers": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "name"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                }
              }
            }
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MatrixRow"
            }
          },
          "providerAverages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MatrixProviderAverage"
            }
          },
          "summary": {
            "$ref": "#/components/schemas/MatrixSummary"
          }
        }
      },
      "MatrixRow": {
        "type": "object",
        "required": [
          "id",
          "name",
          "mentionRate",
          "coverage",
          "overall",
          "cells"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "promptCount": {
            "type": "integer",
            "description": "Number of prompts represented by this row; omitted for prompts granularity"
          },
          "mentionRate": {
            "type": "number",
            "description": "The pooled row's mention rate, matching overall.subScores.mentionRate when available"
          },
          "coverage": {
            "type": "object",
            "required": [
              "count",
              "total",
              "percentage"
            ],
            "properties": {
              "count": {
                "type": "integer",
                "description": "Providers with a positive mention rate, SELF citation count or citation rate"
              },
              "total": {
                "type": "integer",
                "description": "Number of selected provider columns"
              },
              "percentage": {
                "type": "integer",
                "description": "count / total * 100 rounded to the nearest integer; zero when total is zero"
              }
            }
          },
          "overall": {
            "type": "object",
            "required": [
              "score",
              "answerCount"
            ],
            "description": "Metrics recomputed from pooled answers across selected providers; optional metrics are omitted when no answers exist",
            "properties": {
              "score": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "subScores": {
                "$ref": "#/components/schemas/MatrixSubScores"
              },
              "answerCount": {
                "type": "integer"
              },
              "ranking": {
                "$ref": "#/components/schemas/MatrixRankings"
              }
            }
          },
          "cells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MatrixCell"
            }
          }
        }
      },
      "MatrixSubScores": {
        "type": "object",
        "required": [
          "mentionRate",
          "citationRate",
          "shareOfVoice",
          "sentiment"
        ],
        "description": "Uses the current active SELF/DIRECT competitor classification. Rates\nuse distinct answers; share of voice uses mention occurrence counts.\nEmpty denominators produce zero. Score is the rounded, clamped sum\n0.40 * mentionRate + 0.25 * shareOfVoice + 0.20 * citationRate +\n0.15 * sentiment. When sentiment is null, weights become 0.47,\n0.294 and 0.236 respectively for the first three metrics.\n",
        "properties": {
          "mentionRate": {
            "type": "number",
            "description": "Answers mentioning SELF / answers mentioning any active SELF or DIRECT domain * 100"
          },
          "citationRate": {
            "type": "number",
            "description": "Answers citing SELF / answers citing any active SELF or DIRECT domain * 100"
          },
          "shareOfVoice": {
            "type": "number",
            "description": "SELF mention occurrences / active SELF and DIRECT mention occurrences * 100, capped at 100"
          },
          "sentiment": {
            "type": "number",
            "nullable": true,
            "description": "SELF sentiment sum / SELF sentiment sample count; null when no sample exists"
          }
        }
      },
      "MatrixCell": {
        "type": "object",
        "required": [
          "provider",
          "score",
          "citations",
          "position",
          "topCompetitor",
          "topCompetitors",
          "topSources"
        ],
        "properties": {
          "provider": {
            "type": "string"
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "nullable": true,
            "description": "Weighted visibility score; null when this provider has no answers in the row"
          },
          "subScores": {
            "$ref": "#/components/schemas/MatrixSubScores"
          },
          "ranking": {
            "$ref": "#/components/schemas/MatrixRankings"
          },
          "citations": {
            "type": "integer",
            "description": "SELF citation occurrences in the selected scope"
          },
          "position": {
            "type": "number",
            "nullable": true,
            "description": "Minimum SELF mention position in the selected scope"
          },
          "topCompetitor": {
            "type": "string",
            "nullable": true,
            "description": "Name of the first topCompetitors entry"
          },
          "topCompetitors": {
            "type": "array",
            "maxItems": 5,
            "description": "Mentioned competitors grouped by current display name, ordered by mentions descending then mean position and name",
            "items": {
              "type": "object",
              "required": [
                "id",
                "name",
                "domain",
                "mentions",
                "avgPosition",
                "relationship"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "nullable": true
                },
                "name": {
                  "type": "string"
                },
                "domain": {
                  "type": "string",
                  "nullable": true
                },
                "mentions": {
                  "type": "integer"
                },
                "avgPosition": {
                  "type": "number",
                  "nullable": true
                },
                "relationship": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "topSources": {
            "type": "array",
            "maxItems": 5,
            "description": "Cited domains ordered by citations descending then mean position and domain",
            "items": {
              "type": "object",
              "required": [
                "id",
                "domain",
                "citations",
                "avgPosition",
                "relationship"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "nullable": true
                },
                "domain": {
                  "type": "string"
                },
                "citations": {
                  "type": "integer"
                },
                "avgPosition": {
                  "type": "number",
                  "nullable": true
                },
                "relationship": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          }
        }
      },
      "MatrixRankingEntry": {
        "type": "object",
        "required": [
          "rank",
          "total"
        ],
        "properties": {
          "rank": {
            "type": "integer",
            "minimum": 0,
            "description": "One-based rank; zero when the selected subject has no qualifying signal for this metric"
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Number ranked for this metric; zero when the subject is unranked"
          }
        }
      },
      "MatrixRankings": {
        "type": "object",
        "required": [
          "score",
          "mentionRate",
          "shareOfVoice",
          "citationRate",
          "sentiment"
        ],
        "description": "Domain-based subject rankings; omitted without a ranking subject or fewer than two competitors with qualifying evidence",
        "properties": {
          "score": {
            "$ref": "#/components/schemas/MatrixRankingEntry"
          },
          "mentionRate": {
            "$ref": "#/components/schemas/MatrixRankingEntry"
          },
          "shareOfVoice": {
            "$ref": "#/components/schemas/MatrixRankingEntry"
          },
          "citationRate": {
            "$ref": "#/components/schemas/MatrixRankingEntry"
          },
          "sentiment": {
            "$ref": "#/components/schemas/MatrixRankingEntry"
          }
        }
      },
      "MatrixProviderAverage": {
        "type": "object",
        "required": [
          "provider",
          "score",
          "mentionRate",
          "shareOfVoice",
          "citationRate",
          "sentiment"
        ],
        "description": "Rounded arithmetic mean of each non-null cell metric across every matching row, before limit; null when no values exist",
        "properties": {
          "provider": {
            "type": "string"
          },
          "score": {
            "type": "number",
            "nullable": true
          },
          "mentionRate": {
            "type": "number",
            "nullable": true
          },
          "shareOfVoice": {
            "type": "number",
            "nullable": true
          },
          "citationRate": {
            "type": "number",
            "nullable": true
          },
          "sentiment": {
            "type": "number",
            "nullable": true
          }
        }
      },
      "MatrixSummaryRow": {
        "type": "object",
        "nullable": true,
        "required": [
          "rowId",
          "rowName",
          "mentionRate"
        ],
        "properties": {
          "rowId": {
            "type": "string"
          },
          "rowName": {
            "type": "string"
          },
          "mentionRate": {
            "type": "number"
          }
        }
      },
      "MatrixSummary": {
        "type": "object",
        "required": [
          "totalRows",
          "averageMentionRate",
          "topPerforming",
          "needsAttention"
        ],
        "properties": {
          "totalRows": {
            "type": "integer",
            "description": "Total matching rows before limit"
          },
          "averageMentionRate": {
            "type": "integer",
            "description": "Rounded mean of positive row mention rates; zero if none are positive"
          },
          "topPerforming": {
            "$ref": "#/components/schemas/MatrixSummaryRow"
          },
          "needsAttention": {
            "$ref": "#/components/schemas/MatrixSummaryRow"
          }
        }
      },
      "PerceptionScores": {
        "type": "object",
        "required": [
          "sentiment",
          "alignment",
          "consistency",
          "factualAlignment"
        ],
        "properties": {
          "sentiment": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "nullable": true
          },
          "alignment": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "nullable": true
          },
          "consistency": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "nullable": true
          },
          "factualAlignment": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "nullable": true
          }
        }
      },
      "PerceptionSnapshot": {
        "type": "object",
        "nullable": true,
        "required": [
          "snapshotId",
          "month",
          "year",
          "scores",
          "completedAt"
        ],
        "properties": {
          "snapshotId": {
            "type": "string"
          },
          "month": {
            "type": "integer",
            "minimum": 1,
            "maximum": 12
          },
          "year": {
            "type": "integer"
          },
          "scores": {
            "$ref": "#/components/schemas/PerceptionScores"
          },
          "completedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "PerceptionResponse": {
        "type": "object",
        "required": [
          "success",
          "brand",
          "current",
          "previous",
          "trends",
          "averages",
          "history",
          "meta",
          "nextAnalysisDate"
        ],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "brand": {
            "$ref": "#/components/schemas/AnalyticsBrand"
          },
          "current": {
            "$ref": "#/components/schemas/PerceptionSnapshot"
          },
          "previous": {
            "$ref": "#/components/schemas/PerceptionSnapshot"
          },
          "trends": {
            "type": "object",
            "required": [
              "sentiment",
              "alignment",
              "consistency",
              "factualAlignment"
            ],
            "description": "Current minus previous score in points; null when either score is unavailable",
            "properties": {
              "sentiment": {
                "type": "number",
                "nullable": true
              },
              "alignment": {
                "type": "number",
                "nullable": true
              },
              "consistency": {
                "type": "number",
                "nullable": true
              },
              "factualAlignment": {
                "type": "number",
                "nullable": true
              }
            }
          },
          "averages": {
            "$ref": "#/components/schemas/PerceptionScores"
          },
          "history": {
            "type": "array",
            "description": "Completed snapshots in ascending year/month order; multiple snapshots may exist for one month",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/PerceptionSnapshot"
                },
                {
                  "type": "object",
                  "required": [
                    "label"
                  ],
                  "properties": {
                    "label": {
                      "type": "string",
                      "example": "08/2026"
                    }
                  }
                }
              ]
            }
          },
          "meta": {
            "type": "object",
            "required": [
              "months",
              "dataPoints"
            ],
            "properties": {
              "months": {
                "type": "integer"
              },
              "dataPoints": {
                "type": "integer"
              }
            }
          },
          "nextAnalysisDate": {
            "type": "string",
            "format": "date-time",
            "description": "First day of the month after the latest snapshot, or next month if there is no snapshot; an indicative date, not an execution guarantee"
          }
        }
      },
      "PerceptionSnapshotDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PerceptionSnapshot"
          },
          {
            "type": "object",
            "required": [
              "attributes",
              "attributeMetrics",
              "insights",
              "providers",
              "createdAt"
            ],
            "properties": {
              "attributes": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "text",
                    "status"
                  ],
                  "properties": {
                    "text": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "aligned",
                        "partial",
                        "missing"
                      ]
                    }
                  }
                }
              },
              "attributeMetrics": {
                "type": "object",
                "required": [
                  "aligned",
                  "partial",
                  "missing",
                  "total"
                ],
                "properties": {
                  "aligned": {
                    "type": "integer"
                  },
                  "partial": {
                    "type": "integer"
                  },
                  "missing": {
                    "type": "integer"
                  },
                  "total": {
                    "type": "integer"
                  }
                }
              },
              "insights": {
                "type": "object",
                "required": [
                  "strengths",
                  "weaknesses",
                  "opportunities",
                  "threats"
                ],
                "description": "Flat insight titles from current or legacy SWOT data",
                "properties": {
                  "strengths": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "weaknesses": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "opportunities": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "threats": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              },
              "providers": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        ]
      },
      "PromptEvolution": {
        "type": "object",
        "required": [
          "success",
          "prompt",
          "evolution"
        ],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "prompt": {
            "type": "object",
            "required": [
              "id",
              "text"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "text": {
                "type": "string"
              }
            }
          },
          "evolution": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "date",
                "answers",
                "mentionRate",
                "sourceRate",
                "avgSentiment"
              ],
              "properties": {
                "date": {
                  "type": "string",
                  "format": "date"
                },
                "answers": {
                  "type": "integer",
                  "description": "Distinct non-deleted answers for this day and selected providers"
                },
                "mentionRate": {
                  "type": "number",
                  "description": "Distinct answers with a SELF mention / distinct answers with a SELF or DIRECT mention * 100, rounded to two decimals; zero for an empty denominator"
                },
                "sourceRate": {
                  "type": "number",
                  "description": "Distinct answers citing a SELF domain / distinct answers citing a SELF or DIRECT domain * 100, rounded to two decimals; zero for an empty denominator"
                },
                "avgSentiment": {
                  "type": "number",
                  "nullable": true,
                  "description": "SELF sentiment sum / SELF sentiment count, rounded to two decimals; absent and numeric zero results are returned as null"
                }
              }
            }
          }
        }
      },
      "TechnicalFileAnalysis": {
        "type": "object",
        "nullable": true,
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "present",
              "missing",
              "error",
              "invalid"
            ]
          },
          "content": {
            "type": "string"
          },
          "finalUrl": {
            "type": "string"
          },
          "redirected": {
            "type": "boolean"
          },
          "error": {
            "type": "string"
          },
          "crawlers": {
            "type": "object",
            "description": "Map keyed by crawler name",
            "additionalProperties": {
              "type": "object",
              "required": [
                "status",
                "reason"
              ],
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "Allowed",
                    "Disallowed",
                    "Partial"
                  ]
                },
                "reason": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "AiReadiness": {
        "type": "object",
        "nullable": true,
        "required": [
          "score",
          "issuesCount",
          "optimizationsCount"
        ],
        "properties": {
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "20 points for each present file (robots.txt, llms.txt, sitemap.xml), plus round(accessible crawlers / parsed crawlers * 40). Allowed and Partial count as accessible; no parsed crawlers contribute zero points."
          },
          "issuesCount": {
            "type": "integer",
            "description": "One for a non-present robots analysis, plus one when parsed crawlers exist and none is accessible"
          },
          "optimizationsCount": {
            "type": "integer",
            "description": "One each for non-present llms/sitemap analyses, plus one when only some parsed crawlers are accessible"
          }
        }
      },
      "TechnicalAnalysisResponse": {
        "type": "object",
        "required": [
          "success",
          "brand",
          "analyzed",
          "aiReadiness",
          "robotsAnalysis",
          "llmsAnalysis",
          "sitemapAnalysis",
          "lastAnalyzedAt",
          "generatedLlmsTxt"
        ],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "brand": {
            "$ref": "#/components/schemas/AnalyticsBrand"
          },
          "analyzed": {
            "type": "boolean"
          },
          "aiReadiness": {
            "$ref": "#/components/schemas/AiReadiness"
          },
          "robotsUrl": {
            "type": "string",
            "nullable": true,
            "description": "Present only when analyzed is true"
          },
          "llmsUrl": {
            "type": "string",
            "nullable": true,
            "description": "Present only when analyzed is true"
          },
          "sitemapUrl": {
            "type": "string",
            "nullable": true,
            "description": "Present only when analyzed is true"
          },
          "robotsAnalysis": {
            "$ref": "#/components/schemas/TechnicalFileAnalysis"
          },
          "llmsAnalysis": {
            "$ref": "#/components/schemas/TechnicalFileAnalysis"
          },
          "sitemapAnalysis": {
            "$ref": "#/components/schemas/TechnicalFileAnalysis"
          },
          "lastAnalyzedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "generatedLlmsTxt": {
            "type": "string",
            "nullable": true
          },
          "message": {
            "type": "string",
            "description": "Present when analyzed is false; explains how to obtain the first analysis"
          }
        }
      },
      "PitchAuditPrompt": {
        "type": "object",
        "required": [
          "id",
          "text",
          "category",
          "topic"
        ],
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 50
          },
          "text": {
            "type": "string",
            "maxLength": 1000
          },
          "category": {
            "type": "string",
            "enum": [
              "TOFU",
              "MOFU",
              "BOFU"
            ]
          },
          "topic": {
            "type": "string",
            "maxLength": 120
          }
        }
      },
      "PitchAuditCommandStatus": {
        "type": "object",
        "required": [
          "id",
          "requiredCredits",
          "availableCredits",
          "dispatchStatus"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "reportUrl": {
            "type": "string"
          },
          "requiredCredits": {
            "type": "integer"
          },
          "availableCredits": {
            "type": "integer"
          },
          "dispatchStatus": {
            "type": "string",
            "enum": [
              "QUEUED",
              "RECOVERING"
            ]
          }
        }
      },
      "PitchAuditListItem": {
        "type": "object",
        "required": [
          "id",
          "domain",
          "status",
          "reportReady",
          "reportUrl",
          "creditsCharged"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "brandName": {
            "type": "string",
            "nullable": true
          },
          "domain": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "RUNNING",
              "RECOVERING",
              "AWAITING_PROMPTS",
              "COMPLETED",
              "FAILED"
            ]
          },
          "phase": {
            "type": "string",
            "enum": [
              "BUILD",
              "PROMPT_REVIEW",
              "RESPONSE"
            ]
          },
          "currentStage": {
            "type": "string",
            "nullable": true
          },
          "countryCode": {
            "type": "string"
          },
          "measureModelIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "promptCount": {
            "type": "integer",
            "nullable": true
          },
          "competitorCount": {
            "type": "integer"
          },
          "reportReady": {
            "type": "boolean"
          },
          "reportUrl": {
            "type": "string"
          },
          "creditsCharged": {
            "type": "integer"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "completedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "PitchAuditReportEnvelope": {
        "type": "object",
        "required": [
          "success",
          "team",
          "revision",
          "audit"
        ],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "team": {
            "type": "object",
            "required": [
              "id",
              "name"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "revision": {
            "type": "integer",
            "format": "int64"
          },
          "audit": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "BrandSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "domain": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "DRAFT",
              "LIVE",
              "ARCHIVED"
            ]
          },
          "version": {
            "type": "integer",
            "description": "Current version, used as the ETag for conditional writes"
          }
        }
      },
      "BrandDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Workspace"
          },
          {
            "type": "object",
            "properties": {
              "stats": {
                "type": "object",
                "properties": {
                  "promptsCount": {
                    "type": "integer"
                  },
                  "answersCount": {
                    "type": "integer"
                  },
                  "competitorsCount": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        ]
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of items matching filters"
          },
          "count": {
            "type": "integer",
            "description": "Number of items in this response"
          },
          "limit": {
            "type": "integer",
            "description": "Maximum items per page"
          },
          "offset": {
            "type": "integer",
            "description": "Number of items skipped"
          }
        }
      },
      "QueryFanOutPrompt": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Prompt ID"
          },
          "text": {
            "type": "string",
            "description": "Prompt text"
          }
        }
      },
      "SearchInsight": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "occurrences": {
            "type": "integer"
          },
          "priority": {
            "type": "string",
            "enum": [
              "very-high",
              "high",
              "medium",
              "low"
            ]
          },
          "brandPresence": {
            "type": "integer",
            "description": "Number of responses where the brand is present"
          },
          "competitorPresence": {
            "type": "integer",
            "description": "Number of responses where direct competitors are present"
          },
          "competitors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "uniquePrompts": {
            "type": "integer"
          },
          "prompts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QueryFanOutPrompt"
            }
          },
          "uniqueAnswers": {
            "type": "integer"
          },
          "uniqueModels": {
            "type": "integer"
          },
          "models": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "firstSeen": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "lastSeen": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "AnswerQueryFanOut": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "query": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PromptQueryFanOut": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "occurrences": {
            "type": "integer"
          },
          "uniqueAnswers": {
            "type": "integer"
          },
          "models": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "firstSeen": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "lastSeen": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "Competitor": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "domain": {
            "type": "string",
            "nullable": true
          },
          "relationship": {
            "type": "string",
            "enum": [
              "SELF",
              "DIRECT",
              "INDIRECT",
              "ECOSYSTEM",
              "COMPLEMENTARY"
            ]
          },
          "totalMentions": {
            "type": "integer"
          },
          "shareOfVoice": {
            "type": "number",
            "format": "float"
          },
          "avgPosition": {
            "type": "number",
            "format": "float",
            "nullable": true
          },
          "avgSentiment": {
            "type": "number",
            "format": "float",
            "nullable": true
          }
        }
      },
      "CompetitorDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Competitor"
          },
          {
            "type": "object",
            "properties": {
              "byProvider": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "type": "string"
                    },
                    "mentions": {
                      "type": "integer"
                    },
                    "avgPosition": {
                      "type": "number",
                      "format": "float",
                      "nullable": true
                    }
                  }
                }
              },
              "byTopic": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "topic": {
                      "type": "string"
                    },
                    "mentions": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "CompetitorEvolution": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "competitor": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "relationship": {
                "type": "string"
              }
            }
          },
          "evolution": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "format": "date"
                },
                "mentions": {
                  "type": "integer"
                },
                "shareOfVoice": {
                  "type": "number",
                  "format": "float"
                },
                "avgPosition": {
                  "type": "number",
                  "format": "float",
                  "nullable": true
                },
                "avgSentiment": {
                  "type": "number",
                  "format": "float",
                  "nullable": true
                }
              }
            }
          }
        }
      },
      "Source": {
        "type": "object",
        "required": [
          "id",
          "domain",
          "type",
          "isSelf",
          "totalMentions",
          "rate",
          "avgPosition",
          "aiSourceAuthorityScore"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "INSTITUTIONAL",
              "COMMERCIAL",
              "MEDIA",
              "BLOG",
              "FORUM",
              "SOCIAL",
              "EDUCATIONAL",
              "REFERENCE",
              "OTHER"
            ]
          },
          "isSelf": {
            "type": "boolean"
          },
          "totalMentions": {
            "type": "integer"
          },
          "rate": {
            "type": "number",
            "format": "float"
          },
          "avgPosition": {
            "type": "number",
            "format": "float",
            "nullable": true
          },
          "aiSourceAuthorityScore": {
            "type": "number",
            "nullable": true,
            "description": "Latest available public AI Source Authority score; null when absent or based on insufficient data"
          }
        }
      },
      "SourceDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Source"
          },
          {
            "type": "object",
            "required": [
              "status",
              "byProvider",
              "byTopic"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "ACTIVE",
                  "OFFLINE",
                  "NOT_FOUND",
                  "ERROR",
                  "FAILED"
                ]
              },
              "byProvider": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "type": "string"
                    },
                    "mentions": {
                      "type": "integer"
                    },
                    "avgPosition": {
                      "type": "number",
                      "format": "float",
                      "nullable": true
                    }
                  }
                }
              },
              "byTopic": {
                "type": "array",
                "maxItems": 10,
                "items": {
                  "type": "object",
                  "properties": {
                    "topic": {
                      "type": "string"
                    },
                    "mentions": {
                      "type": "integer"
                    },
                    "avgPosition": {
                      "type": "number",
                      "format": "float",
                      "nullable": true
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "SourceEvolution": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "source": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "domain": {
                "type": "string"
              },
              "isSelf": {
                "type": "boolean"
              }
            }
          },
          "evolution": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "format": "date"
                },
                "mentions": {
                  "type": "integer"
                },
                "avgPosition": {
                  "type": "number",
                  "format": "float",
                  "nullable": true
                }
              }
            }
          }
        }
      },
      "Prompt": {
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/PromptEnrichment"
          }
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "topic": {
            "type": "string",
            "nullable": true
          },
          "type": {
            "type": "string",
            "enum": [
              "TOFU",
              "MOFU",
              "BOFU",
              "POST_PURCHASE"
            ],
            "nullable": true
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "personas": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Persona"
            }
          },
          "modelIds": {
            "type": "array",
            "description": "Model IDs configured specifically for this prompt. An empty array means the workspace defaults apply.",
            "items": {
              "type": "string"
            }
          },
          "monitoringEnabled": {
            "type": "boolean"
          },
          "frequency": {
            "type": "string",
            "enum": [
              "NONE",
              "DAILY",
              "WEEKLY",
              "MONTHLY"
            ],
            "nullable": true,
            "description": "Effective monitoring frequency."
          },
          "frequencyInherited": {
            "type": "boolean"
          },
          "boostCount": {
            "type": "integer",
            "minimum": 1
          },
          "answersCount": {
            "type": "integer"
          },
          "mentionRate": {
            "type": "number",
            "format": "float"
          },
          "sourceRate": {
            "type": "number",
            "format": "float"
          },
          "lastGeneratedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "competitors": {
            "type": "array",
            "description": "Returned only when include=details.",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/PromptCompetitor"
                },
                {
                  "type": "object",
                  "properties": {
                    "domain": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              ]
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Returned only when include=details."
          }
        }
      },
      "PromptDetail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "topic": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "type": {
            "type": "string",
            "enum": [
              "TOFU",
              "MOFU",
              "BOFU",
              "POST_PURCHASE"
            ],
            "nullable": true
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                }
              }
            }
          },
          "answersCount": {
            "type": "integer"
          },
          "mentionRate": {
            "type": "number",
            "format": "float"
          },
          "sourceRate": {
            "type": "number",
            "format": "float"
          },
          "avgSentiment": {
            "type": "number",
            "format": "float",
            "nullable": true
          },
          "queryFanOutsTotal": {
            "type": "integer",
            "description": "Total number of query fan-outs for this prompt"
          },
          "queryFanOutsLimit": {
            "type": "integer",
            "description": "Maximum number of query fan-outs returned"
          },
          "queryFanOuts": {
            "type": "array",
            "description": "Top query fan-outs for this prompt, ordered by occurrences",
            "items": {
              "$ref": "#/components/schemas/PromptQueryFanOut"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastGeneratedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "ARCHIVED"
            ]
          },
          "frequency": {
            "type": "string",
            "nullable": true,
            "enum": [
              "NONE",
              "DAILY",
              "WEEKLY",
              "MONTHLY"
            ],
            "description": "Effective monitoring frequency."
          },
          "monitoringEnabled": {
            "type": "boolean"
          },
          "keywordId": {
            "type": "string",
            "nullable": true
          },
          "tagIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "version": {
            "type": "integer"
          },
          "personas": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Persona"
            }
          },
          "modelIds": {
            "type": "array",
            "description": "Model IDs configured specifically for this prompt. An empty array means the workspace defaults apply.",
            "items": {
              "type": "string"
            }
          },
          "frequencyInherited": {
            "type": "boolean"
          },
          "boostCount": {
            "type": "integer",
            "minimum": 1
          },
          "competitors": {
            "type": "array",
            "description": "Returned only when include=details.",
            "items": {
              "$ref": "#/components/schemas/PromptCompetitor"
            }
          }
        },
        "allOf": [
          {
            "$ref": "#/components/schemas/PromptEnrichment"
          }
        ]
      },
      "AnswerSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/AnswerStatus"
          },
          "promptId": {
            "type": "string"
          },
          "promptText": {
            "type": "string",
            "nullable": true
          },
          "provider": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "persona": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Persona"
              }
            ],
            "nullable": true,
            "description": "Immutable persona snapshot used for generation, or null for the default persona."
          },
          "textPreview": {
            "type": "string",
            "description": "First 200 characters of the response, followed by ... when truncated (up to 203 characters)."
          },
          "hasSelfMention": {
            "type": "boolean"
          },
          "selfMentionPosition": {
            "type": "integer",
            "nullable": true
          },
          "hasSelfSource": {
            "type": "boolean"
          },
          "competitorsCount": {
            "type": "integer"
          },
          "sourcesCount": {
            "type": "integer"
          },
          "sentiment": {
            "type": "number",
            "format": "float",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AnswerFull": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/AnswerStatus"
          },
          "provider": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "persona": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Persona"
              }
            ],
            "nullable": true,
            "description": "Immutable persona snapshot used for generation, or null for the default persona."
          },
          "text": {
            "type": "string",
            "nullable": true
          },
          "hasSelfMention": {
            "type": "boolean"
          },
          "selfMentionPosition": {
            "type": "integer",
            "nullable": true
          },
          "hasSelfSource": {
            "type": "boolean"
          },
          "competitorsMentioned": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sourcesCited": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sentiment": {
            "type": "number",
            "format": "float",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AnswerDetail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/AnswerStatus"
          },
          "prompt": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "nullable": true
              },
              "text": {
                "type": "string",
                "nullable": true
              },
              "topic": {
                "type": "string",
                "nullable": true
              },
              "type": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "provider": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "persona": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Persona"
              }
            ],
            "nullable": true,
            "description": "Immutable persona snapshot used for generation, or null for the default persona."
          },
          "text": {
            "type": "string",
            "nullable": true
          },
          "competitors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "nullable": true
                },
                "position": {
                  "type": "integer",
                  "nullable": true
                },
                "relationship": {
                  "type": "string",
                  "enum": [
                    "SELF",
                    "DIRECT",
                    "INDIRECT",
                    "ECOSYSTEM",
                    "COMPLEMENTARY",
                    null
                  ],
                  "nullable": true
                },
                "sentiment": {
                  "type": "number",
                  "format": "float",
                  "nullable": true
                }
              }
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string",
                  "nullable": true
                },
                "domain": {
                  "type": "string",
                  "nullable": true
                },
                "position": {
                  "type": "integer"
                },
                "isSelf": {
                  "type": "boolean"
                }
              }
            }
          },
          "queryFanOuts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AnswerQueryFanOut"
            }
          },
          "sentiment": {
            "type": "number",
            "format": "float",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PerformanceSnapshot": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "brand": {
            "$ref": "#/components/schemas/BrandSummary"
          },
          "period": {
            "type": "object",
            "properties": {
              "start": {
                "type": "string",
                "format": "date",
                "nullable": true
              },
              "end": {
                "type": "string",
                "format": "date",
                "nullable": true
              }
            }
          },
          "methodology": {
            "type": "object",
            "properties": {
              "promptsCount": {
                "type": "integer"
              },
              "providersCount": {
                "type": "integer"
              },
              "providers": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "responsesTotal": {
                "type": "integer"
              },
              "responsesWithMentions": {
                "type": "integer"
              },
              "responsesWithSources": {
                "type": "integer"
              }
            }
          },
          "scores": {
            "type": "object",
            "properties": {
              "mentionRate": {
                "type": "number",
                "format": "float"
              },
              "mentionCount": {
                "type": "integer"
              },
              "mentionTotal": {
                "type": "integer"
              },
              "coverage": {
                "type": "number",
                "format": "float"
              },
              "sourceRate": {
                "type": "number",
                "format": "float"
              },
              "sourceCount": {
                "type": "integer"
              },
              "sourceTotal": {
                "type": "integer"
              },
              "sourcePages": {
                "type": "integer"
              },
              "sentiment": {
                "type": "number",
                "format": "float"
              },
              "shareOfVoice": {
                "type": "number",
                "format": "float"
              }
            }
          },
          "topCompetitors": {
            "type": "array",
            "maxItems": 5,
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string",
                  "nullable": true
                },
                "relationship": {
                  "type": "string",
                  "enum": [
                    "SELF",
                    "DIRECT"
                  ]
                },
                "mentions": {
                  "type": "integer"
                },
                "avgPosition": {
                  "type": "number",
                  "format": "float",
                  "nullable": true
                },
                "avgSentiment": {
                  "type": "number",
                  "format": "float",
                  "nullable": true
                }
              }
            }
          },
          "topSources": {
            "type": "array",
            "maxItems": 5,
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "domain": {
                  "type": "string"
                },
                "isSelf": {
                  "type": "boolean"
                },
                "mentions": {
                  "type": "integer"
                },
                "avgPosition": {
                  "type": "number",
                  "format": "float",
                  "nullable": true
                }
              }
            }
          },
          "byTopic": {
            "type": "array",
            "description": "Top topics of the scoped answers. Scores are the GEO Matrix Overall values for each topic over the same period and filters.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "topic": {
                  "type": "string"
                },
                "score": {
                  "type": "number",
                  "format": "float",
                  "description": "GEO Matrix Overall score (0-100)."
                },
                "mentionRate": {
                  "type": "number",
                  "format": "float"
                },
                "sourceRate": {
                  "type": "number",
                  "format": "float",
                  "description": "Brand citation rate used by the score."
                },
                "shareOfVoice": {
                  "type": "number",
                  "format": "float"
                },
                "avgSentiment": {
                  "type": "number",
                  "format": "float",
                  "nullable": true,
                  "description": "Average brand sentiment used by the score."
                },
                "promptsCount": {
                  "type": "integer"
                }
              }
            }
          },
          "byTag": {
            "type": "array",
            "description": "Tags carried by the scoped prompts. Scores are the GEO Matrix Overall values for each tag over the same period and filters.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "score": {
                  "type": "number",
                  "format": "float",
                  "description": "GEO Matrix Overall score (0-100)."
                },
                "mentionRate": {
                  "type": "number",
                  "format": "float"
                },
                "sourceRate": {
                  "type": "number",
                  "format": "float",
                  "description": "Brand citation rate used by the score."
                },
                "shareOfVoice": {
                  "type": "number",
                  "format": "float"
                },
                "avgSentiment": {
                  "type": "number",
                  "format": "float",
                  "nullable": true,
                  "description": "Average brand sentiment used by the score."
                },
                "promptsCount": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "CrawlerAnalyticsResponse": {
        "type": "object",
        "required": [
          "success",
          "rawEventsAvailable",
          "humanTrafficIncluded",
          "brand",
          "connected",
          "lifecycle",
          "health",
          "range",
          "coverage",
          "totalOccurrences",
          "identifiedPageOccurrences",
          "redirectOccurrences",
          "notFoundOccurrences",
          "otherErrorOccurrences",
          "buckets",
          "crawlerStats",
          "pages",
          "pagination"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "rawEventsAvailable": {
            "type": "boolean",
            "enum": [
              false
            ],
            "description": "Raw server log events are not retained or exposed."
          },
          "humanTrafficIncluded": {
            "type": "boolean",
            "enum": [
              false
            ],
            "description": "Human traffic is excluded before analytical persistence."
          },
          "brand": {
            "$ref": "#/components/schemas/BrandSummary"
          },
          "connected": {
            "type": "boolean",
            "description": "Whether the crawler integration is currently active with an active key."
          },
          "lifecycle": {
            "type": "string",
            "enum": [
              "PENDING",
              "ACTIVE",
              "PAUSED",
              "DISABLED"
            ],
            "nullable": true
          },
          "health": {
            "type": "string",
            "enum": [
              "SETUP_REQUIRED",
              "HEALTHY",
              "DEGRADED",
              "SILENT_UNVERIFIED",
              "STALE",
              "ERROR",
              "DISABLED"
            ],
            "nullable": true
          },
          "range": {
            "$ref": "#/components/schemas/CrawlerAnalyticsRange"
          },
          "coverage": {
            "$ref": "#/components/schemas/CrawlerAnalyticsCoverage"
          },
          "totalOccurrences": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "nullable": true,
            "description": "Observed AI crawler occurrences, or null when the period was not measured."
          },
          "identifiedPageOccurrences": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "description": "Requests linked to a page identity in the retained period."
          },
          "redirectOccurrences": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "notFoundOccurrences": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "otherErrorOccurrences": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "buckets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CrawlerAnalyticsBucket"
            }
          },
          "crawlerStats": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CrawlerAnalyticsCrawler"
            }
          },
          "pages": {
            "type": "array",
            "description": "Current page of the listed pages (active in the range unless activeOnly=false), ordered by period volume.",
            "items": {
              "$ref": "#/components/schemas/CrawlerAnalyticsPage"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/CrawlerAnalyticsPagination"
          }
        }
      },
      "CrawlerAnalyticsRange": {
        "type": "object",
        "required": [
          "startDate",
          "requestedEndDate",
          "endDate",
          "elapsedBucketCount",
          "observedBucketCount",
          "verifiedBucketCount",
          "rangeTruncated",
          "asOf"
        ],
        "properties": {
          "requestedEndDate": {
            "type": "string",
            "format": "date"
          },
          "startDate": {
            "type": "string",
            "format": "date",
            "description": "Effective retained start date."
          },
          "endDate": {
            "type": "string",
            "format": "date",
            "description": "Effective retained end date."
          },
          "elapsedBucketCount": {
            "type": "integer",
            "minimum": 0
          },
          "observedBucketCount": {
            "type": "integer",
            "minimum": 0
          },
          "verifiedBucketCount": {
            "type": "integer",
            "minimum": 0
          },
          "rangeTruncated": {
            "type": "boolean"
          },
          "asOf": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CrawlerAnalyticsCoverage": {
        "type": "object",
        "required": [
          "hasObservations",
          "dataStatus",
          "ingestCoverageFlags",
          "countPrecision",
          "deliveryContinuity"
        ],
        "properties": {
          "hasObservations": {
            "type": "boolean"
          },
          "dataStatus": {
            "type": "string",
            "enum": [
              "observed",
              "not_measured",
              "incomplete_ingestion"
            ]
          },
          "ingestCoverageFlags": {
            "type": "integer",
            "minimum": 0,
            "description": "Bit mask describing delivery, provider, or technical-limit caveats."
          },
          "countPrecision": {
            "type": "string",
            "enum": [
              "exact",
              "at_least_once",
              "capped"
            ]
          },
          "deliveryContinuity": {
            "type": "string",
            "enum": [
              "verified",
              "unverified",
              "incomplete"
            ]
          }
        }
      },
      "CrawlerAnalyticsBucket": {
        "type": "object",
        "required": [
          "bucketStart",
          "totalOccurrences",
          "crawlerOccurrences",
          "redirectOccurrences",
          "notFoundOccurrences",
          "otherErrorOccurrences",
          "dataStatus",
          "deliveryContinuity",
          "ingestCoverageFlags"
        ],
        "properties": {
          "bucketStart": {
            "type": "string",
            "format": "date"
          },
          "totalOccurrences": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "nullable": true
          },
          "crawlerOccurrences": {
            "type": "object",
            "additionalProperties": {
              "type": "integer",
              "format": "int64",
              "minimum": 0
            }
          },
          "redirectOccurrences": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "notFoundOccurrences": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "otherErrorOccurrences": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "dataStatus": {
            "type": "string",
            "enum": [
              "observed",
              "not_measured",
              "incomplete_ingestion"
            ]
          },
          "deliveryContinuity": {
            "type": "string",
            "enum": [
              "verified",
              "unverified",
              "incomplete"
            ]
          },
          "ingestCoverageFlags": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "CrawlerAnalyticsCrawler": {
        "type": "object",
        "required": [
          "crawlerId",
          "name",
          "displayName",
          "totalOccurrences",
          "redirectOccurrences",
          "notFoundOccurrences",
          "otherErrorOccurrences",
          "botType"
        ],
        "properties": {
          "crawlerId": {
            "type": "integer",
            "minimum": 1
          },
          "name": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          },
          "totalOccurrences": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "redirectOccurrences": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "notFoundOccurrences": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "otherErrorOccurrences": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "botType": {
            "type": "string",
            "enum": [
              "training",
              "search",
              "userQuery",
              "agent",
              "other"
            ]
          }
        }
      },
      "CrawlerAnalyticsPage": {
        "type": "object",
        "required": [
          "pathId",
          "path",
          "isPseudonymized",
          "firstSeenAt",
          "lastSeenAt",
          "lifetimeCount",
          "states",
          "occurrences",
          "crawlerOccurrences",
          "uniqueCrawlers",
          "statusGroups",
          "crawlerTypes"
        ],
        "properties": {
          "pathId": {
            "type": "string",
            "description": "Stable page identifier for the integration."
          },
          "path": {
            "type": "string",
            "description": "Normalized path without query string or fragment."
          },
          "isPseudonymized": {
            "type": "boolean",
            "description": "Whether the displayed path is an internal pseudonym and not a reconnectable URL."
          },
          "firstSeenAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastSeenAt": {
            "type": "string",
            "format": "date-time"
          },
          "lifetimeCount": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "states": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "new",
                "hot",
                "neglected"
              ]
            }
          },
          "occurrences": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "crawlerOccurrences": {
            "type": "object",
            "additionalProperties": {
              "type": "integer",
              "format": "int64",
              "minimum": 0
            }
          },
          "uniqueCrawlers": {
            "type": "integer",
            "minimum": 0
          },
          "statusGroups": {
            "$ref": "#/components/schemas/CrawlerAnalyticsStatusGroups"
          },
          "crawlerTypes": {
            "$ref": "#/components/schemas/CrawlerAnalyticsTypeGroups"
          }
        }
      },
      "CrawlerAnalyticsStatusGroups": {
        "type": "object",
        "required": [
          "success2xx",
          "redirect3xx",
          "unauthorized401",
          "forbidden403",
          "notFound404",
          "rateLimited429",
          "other4xx",
          "server5xx",
          "otherStatus",
          "invalidStatus"
        ],
        "properties": {
          "success2xx": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "redirect3xx": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "unauthorized401": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "forbidden403": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "notFound404": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "rateLimited429": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "other4xx": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "server5xx": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "otherStatus": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "invalidStatus": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          }
        }
      },
      "CrawlerAnalyticsTypeGroups": {
        "type": "object",
        "required": [
          "liveSearch",
          "training",
          "other"
        ],
        "properties": {
          "liveSearch": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "training": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "other": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          }
        }
      },
      "CrawlerAnalyticsPagination": {
        "type": "object",
        "required": [
          "page",
          "limit",
          "totalItems",
          "totalPages",
          "hasMore"
        ],
        "properties": {
          "page": {
            "type": "integer",
            "minimum": 1
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          },
          "totalItems": {
            "type": "integer",
            "minimum": 0
          },
          "totalPages": {
            "type": "integer",
            "minimum": 0
          },
          "hasMore": {
            "type": "boolean"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Machine-readable error code"
              },
              "message": {
                "type": "string",
                "description": "Human-readable error message"
              }
            }
          }
        }
      },
      "AuthenticationError": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "example": "Unauthorized"
          },
          "message": {
            "type": "string",
            "example": "Invalid API token or insufficient subscription plan (Growth+ required)"
          }
        }
      },
      "WriteError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "requestId"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code",
                "enum": [
                  "UNAUTHORIZED",
                  "INSUFFICIENT_PLAN",
                  "INVALID_REQUEST",
                  "IDEMPOTENCY_KEY_REQUIRED",
                  "RESOURCE_NOT_FOUND",
                  "CONFLICT",
                  "IDEMPOTENCY_CONFLICT",
                  "IDEMPOTENCY_IN_PROGRESS",
                  "INVALID_STATE_TRANSITION",
                  "RESOURCE_BUSY",
                  "QUOTA_EXCEEDED",
                  "INSUFFICIENT_CREDITS",
                  "PRECONDITION_FAILED",
                  "PRECONDITION_REQUIRED",
                  "RATE_LIMIT_EXCEEDED",
                  "SERVICE_UNAVAILABLE",
                  "INTERNAL_ERROR",
                  "API_KEY_READ_ONLY"
                ]
              },
              "message": {
                "type": "string"
              },
              "requestId": {
                "type": "string",
                "description": "Quote this when contacting support"
              },
              "details": {
                "type": "object",
                "additionalProperties": true,
                "description": "Optional context, at most 20 keys. A validation failure\n(INVALID_REQUEST) lists up to 10 `issues`, each with a `path`\nand a `message`. The workspace creation budget (429 on\nPOST /brands) gives `reason: BRAND_CREATION_DAILY_LIMIT`,\n`limit`, `resetAt` and `retryAfterSeconds`. Some conflicts\nidentify the existing resource, such as `promptId` or `domain`.\n"
              }
            }
          }
        }
      },
      "Workspace": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "languageCode": {
            "type": "string"
          },
          "countryCode": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "DRAFT",
              "LIVE",
              "ARCHIVED"
            ]
          },
          "version": {
            "type": "integer"
          },
          "lifecycleVersion": {
            "type": "integer",
            "description": "Incremented on each activation"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "url": {
            "type": "string",
            "nullable": true
          },
          "countryCodes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "autoDetectCompetitors": {
            "type": "boolean"
          },
          "selfHostScope": {
            "type": "string",
            "enum": [
              "REGISTRABLE",
              "EXACT_HOST",
              "AUTO"
            ]
          }
        }
      },
      "PromptControl": {
        "type": "object",
        "description": "Prompt as returned by the control (write) endpoints",
        "properties": {
          "id": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "ARCHIVED"
            ]
          },
          "frequency": {
            "type": "string",
            "nullable": true,
            "enum": [
              "NONE",
              "DAILY",
              "WEEKLY",
              "MONTHLY"
            ]
          },
          "monitoringEnabled": {
            "type": "boolean"
          },
          "keywordId": {
            "type": "string",
            "nullable": true
          },
          "tagIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "version": {
            "type": "integer"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "countryCodes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "modelIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "TopicControl": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "version": {
            "type": "integer"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TagControl": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "color": {
            "type": "string",
            "nullable": true
          },
          "version": {
            "type": "integer"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "BulkPromptResult": {
        "type": "object",
        "properties": {
          "operation": {
            "type": "string",
            "enum": [
              "archive",
              "restore",
              "frequency",
              "topic",
              "tags"
            ]
          },
          "updated": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "promptId": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "updated",
                    "unchanged",
                    "not_found"
                  ]
                }
              }
            }
          },
          "dryRun": {
            "type": "boolean"
          }
        }
      },
      "GenerationRunsPage": {
        "type": "object",
        "required": [
          "success",
          "runs",
          "nextCursor",
          "totalCount",
          "activeCount"
        ],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "runs": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/RunSummary"
            }
          },
          "nextCursor": {
            "type": "string",
            "nullable": true,
            "description": "Opaque cursor for the next page; null when no further page exists"
          },
          "totalCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Total number of runs in the workspace, across all pages"
          },
          "activeCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of runs with pending planning or active attempts, across all pages"
          }
        }
      },
      "RunPlanning": {
        "type": "object",
        "required": [
          "id",
          "purpose",
          "priority",
          "modelCount",
          "requestedCount",
          "plannedCount",
          "planningCompletedAt",
          "planningFailed",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "purpose": {
            "type": "string",
            "enum": [
              "PERIODIC",
              "PROMPT_ADDED",
              "MANUAL",
              "ONBOARDING"
            ]
          },
          "priority": {
            "type": "string",
            "enum": [
              "URGENT",
              "NORMAL"
            ]
          },
          "modelCount": {
            "type": "integer",
            "minimum": 0
          },
          "requestedCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of requested prompt/model executions"
          },
          "plannedCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of executions retained by planning"
          },
          "planningCompletedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "planningFailed": {
            "type": "boolean",
            "description": "Whether a planning error was recorded"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "RunSummary": {
        "allOf": [
          {
            "$ref": "#/components/schemas/RunPlanning"
          },
          {
            "type": "object",
            "required": [
              "scheduledFrequency",
              "questionCount",
              "status",
              "counts",
              "terminalCount",
              "progressPercentage"
            ],
            "properties": {
              "scheduledFrequency": {
                "type": "string",
                "nullable": true
              },
              "questionCount": {
                "type": "integer",
                "minimum": 0,
                "description": "Number of prompts in the run; the list response uses the name questionCount"
              },
              "status": {
                "type": "string",
                "enum": [
                  "QUEUED",
                  "PROCESSING",
                  "COMPLETED",
                  "COMPLETED_WITH_WARNINGS",
                  "FAILED",
                  "CANCELLED",
                  "NO_WORK"
                ],
                "description": "Computed from planning state and effective attempt outcomes"
              },
              "counts": {
                "$ref": "#/components/schemas/RunCounts"
              },
              "terminalCount": {
                "type": "integer",
                "minimum": 0,
                "description": "Sum of success, warning, failed, cancelled and skipped counts"
              },
              "progressPercentage": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100,
                "description": "Rounded terminalCount / requestedCount * 100, capped at 100; equals 100 when requestedCount is zero"
              }
            }
          }
        ]
      },
      "RunCounts": {
        "type": "object",
        "required": [
          "success",
          "warning",
          "failed",
          "cancelled",
          "processing",
          "queued",
          "skipped"
        ],
        "properties": {
          "success": {
            "type": "integer",
            "minimum": 0,
            "description": "Completed attempts without warnings"
          },
          "warning": {
            "type": "integer",
            "minimum": 0,
            "description": "Partial-error attempts and attempts carrying an execution warning"
          },
          "failed": {
            "type": "integer",
            "minimum": 0,
            "description": "Failed or quarantined attempts"
          },
          "cancelled": {
            "type": "integer",
            "minimum": 0
          },
          "processing": {
            "type": "integer",
            "minimum": 0,
            "description": "Attempts being dispatched, received, normalized or processed"
          },
          "queued": {
            "type": "integer",
            "minimum": 0,
            "description": "Created attempts plus any expected executions whose attempts have not yet been recorded"
          },
          "skipped": {
            "type": "integer",
            "minimum": 0,
            "description": "max(requestedCount - plannedCount, 0) once planning is complete; zero beforehand"
          }
        }
      },
      "RunDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/RunPlanning"
          },
          {
            "type": "object",
            "required": [
              "promptCount",
              "attemptCount"
            ],
            "properties": {
              "promptCount": {
                "type": "integer",
                "minimum": 0
              },
              "attemptCount": {
                "type": "integer",
                "minimum": 0,
                "description": "Number of recorded generation attempts for this run"
              }
            }
          }
        ]
      },
      "StartedRun": {
        "type": "object",
        "properties": {
          "runId": {
            "type": "string"
          },
          "promptCount": {
            "type": "integer"
          },
          "modelCount": {
            "type": "integer"
          },
          "unsupportedModels": {
            "type": "array",
            "description": "Unknown, disabled, unavailable, or country-ineligible model ids excluded before planning",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "RunEstimate": {
        "type": "object",
        "properties": {
          "promptCount": {
            "type": "integer"
          },
          "modelCount": {
            "type": "integer"
          },
          "answerCount": {
            "type": "integer"
          },
          "estimatedCredits": {
            "type": "integer"
          },
          "availableCredits": {
            "type": "integer"
          },
          "sufficientCredits": {
            "type": "boolean"
          },
          "unsupportedModels": {
            "type": "array",
            "description": "Unknown, disabled, unavailable, or country-ineligible model ids excluded from the estimate",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Monitoring": {
        "type": "object",
        "properties": {
          "brandId": {
            "type": "string"
          },
          "frequency": {
            "type": "string",
            "enum": [
              "NONE",
              "DAILY",
              "WEEKLY",
              "MONTHLY"
            ],
            "description": "NONE stops the workspace schedule; prompts with their own frequency keep running"
          },
          "paused": {
            "type": "boolean",
            "description": "True when frequency is NONE. Prompts with their own frequency still run."
          },
          "analysisWeekDay": {
            "type": "integer",
            "nullable": true
          },
          "analysisMonthDay": {
            "type": "integer",
            "nullable": true
          },
          "autoGenerateAnswers": {
            "type": "boolean"
          },
          "models": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "lastAnalysisDate": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "version": {
            "type": "integer"
          },
          "isDefault": {
            "type": "boolean",
            "description": "True when no settings are stored yet and defaults are returned"
          }
        }
      },
      "Credits": {
        "type": "object",
        "properties": {
          "balance": {
            "type": "integer"
          },
          "usedLast30Days": {
            "type": "integer"
          },
          "averageDailyBurn": {
            "type": "number"
          },
          "runwayDays": {
            "type": "integer",
            "nullable": true
          },
          "subTeams": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "object",
              "properties": {
                "teamId": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "balance": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "RateLimitError": {
        "type": "object",
        "required": [
          "error",
          "limit",
          "message",
          "retryAfter"
        ],
        "properties": {
          "error": {
            "type": "string",
            "example": "Too Many Requests"
          },
          "limit": {
            "type": "string",
            "enum": [
              "burst",
              "daily"
            ]
          },
          "message": {
            "type": "string"
          },
          "retryAfter": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "SignalType": {
        "type": "string",
        "enum": [
          "INFORMATIONAL",
          "RECOMMENDATION",
          "COMPARISON",
          "HOW_TO",
          "PROBLEM_SOLVING",
          "TRANSACTIONAL",
          "NAVIGATIONAL",
          "LOCAL",
          "COMMERCE",
          "OTHER"
        ]
      },
      "InternalServerError": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "PromptEnrichment": {
        "type": "object",
        "description": "Additional optional properties returned only when include=details.",
        "properties": {
          "competitorsCount": {
            "type": "integer"
          },
          "competitorMentionsTotal": {
            "type": "integer"
          },
          "brandMentioned": {
            "type": "boolean"
          },
          "brandMentionCount": {
            "type": "integer"
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "domain": {
                  "type": "string"
                },
                "citations": {
                  "type": "integer"
                },
                "isSelf": {
                  "type": "boolean"
                }
              }
            }
          },
          "sourcesCount": {
            "type": "integer"
          },
          "sourceCitationsTotal": {
            "type": "integer"
          },
          "sourceStability": {
            "type": "number"
          }
        }
      },
      "Persona": {
        "type": "object",
        "required": [
          "id",
          "name",
          "description"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "PromptCompetitor": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "mentions": {
            "type": "integer"
          },
          "relationship": {
            "type": "string",
            "enum": [
              "SELF",
              "DIRECT",
              "INDIRECT",
              null
            ],
            "nullable": true
          }
        }
      },
      "AnswerStatus": {
        "type": "string",
        "enum": [
          "PROCESSING",
          "COMPLETED",
          "PARTIAL_ERROR"
        ],
        "description": "Analysis state of the answer. PROCESSING means the text is available but mentions, sources and sentiment are still being computed and may change. COMPLETED means every analysis finished. PARTIAL_ERROR means the text is available but at least one analysis failed, so these fields may be incomplete."
      },
      "PageAuditStatus": {
        "type": "string",
        "enum": [
          "PENDING",
          "AUDITING",
          "COMPLETED",
          "FAILED"
        ]
      },
      "MonitoredPage": {
        "type": "object",
        "required": [
          "id",
          "url",
          "path",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "pageType": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "$ref": "#/components/schemas/PageAuditStatus"
          },
          "aiReadinessScore": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "nullable": true,
            "description": "Current AI Readiness score of the page, from its latest AI Readiness analysis (Optimize). It is not produced by a page audit and does not belong to a given audit; null until the page has been analyzed."
          },
          "openIssues": {
            "type": "integer",
            "minimum": 0
          },
          "lastAuditAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "MonitoredPageList": {
        "type": "object",
        "required": [
          "data",
          "pagination"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MonitoredPage"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "MonitoredPageDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/MonitoredPage"
          },
          {
            "type": "object",
            "required": [
              "issues"
            ],
            "properties": {
              "issues": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "type",
                    "severity",
                    "status",
                    "title"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "TECHNICAL",
                        "CONTENT"
                      ]
                    },
                    "severity": {
                      "type": "string",
                      "enum": [
                        "CRITICAL",
                        "HIGH",
                        "MEDIUM",
                        "LOW"
                      ]
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "OPEN",
                        "RESOLVED",
                        "IGNORED"
                      ]
                    },
                    "title": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "firstDetectedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "lastDetectedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "AddPagesResult": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "url",
                "outcome"
              ],
              "properties": {
                "url": {
                  "type": "string"
                },
                "outcome": {
                  "type": "string",
                  "enum": [
                    "added",
                    "already_monitored",
                    "invalid",
                    "outside_domain"
                  ]
                },
                "pageId": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          }
        }
      },
      "SiteAudit": {
        "type": "object",
        "required": [
          "id",
          "status",
          "pages",
          "counts",
          "creditsReserved",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "nullable": true,
            "description": "Null for a dry run."
          },
          "status": {
            "type": "string",
            "enum": [
              "PREVIEW",
              "RUNNING",
              "COMPLETED"
            ]
          },
          "creditsReserved": {
            "type": "integer",
            "minimum": 0,
            "description": "5 credits per page to audit; for a dry run, the credits the audit would reserve."
          },
          "counts": {
            "type": "object",
            "required": [
              "total",
              "succeeded",
              "failed",
              "skipped",
              "running"
            ],
            "properties": {
              "total": {
                "type": "integer"
              },
              "succeeded": {
                "type": "integer"
              },
              "failed": {
                "type": "integer"
              },
              "skipped": {
                "type": "integer"
              },
              "running": {
                "type": "integer"
              }
            }
          },
          "pages": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "pageId",
                "status"
              ],
              "properties": {
                "pageId": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "QUEUED",
                    "AUDITING",
                    "COMPLETED",
                    "FAILED",
                    "SKIPPED"
                  ]
                },
                "completedAt": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true,
                  "description": "When the page finished. Null while it is QUEUED or AUDITING, and for a SKIPPED page or a failure that carries no date."
                }
              }
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "completedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the audit finished, null while it runs. Once the site_audit.completed event exists, this is the completedAt of that event; it can follow the last page date when the last pages were skipped or the queueing closed later."
          }
        }
      },
      "WebhookEventEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "description": "JSON body of every webhook delivery. Verify X-Qwairy-Signature on the\nraw body before parsing it.\n",
        "required": [
          "id",
          "event",
          "createdAt",
          "teamId",
          "brandId",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Event identifier, the same on every attempt and redelivery"
          },
          "event": {
            "$ref": "#/components/schemas/WebhookEventType"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "teamId": {
            "type": "string"
          },
          "brandId": {
            "type": "string",
            "nullable": true,
            "description": "Workspace of the event; null for team-level events (Pitch Audits, webhook.test)"
          },
          "data": {
            "description": "Event payload. run.completed, run.failed and run.cancelled:\nWebhookRunEventData. pitch_audit.completed:\nWebhookPitchAuditCompletedData. pitch_audit.failed:\nWebhookPitchAuditFailedData. site_audit.completed:\nWebhookSiteAuditCompletedData. prompt_suggestions.ready:\nWebhookPromptSuggestionsReadyData. prompt_suggestions.failed:\nWebhookPromptSuggestionsFailedData. webhook.test:\nWebhookTestEventData.\n",
            "oneOf": [
              {
                "$ref": "#/components/schemas/WebhookRunEventData"
              },
              {
                "$ref": "#/components/schemas/WebhookPitchAuditCompletedData"
              },
              {
                "$ref": "#/components/schemas/WebhookPitchAuditFailedData"
              },
              {
                "$ref": "#/components/schemas/WebhookSiteAuditCompletedData"
              },
              {
                "$ref": "#/components/schemas/WebhookPromptSuggestionsReadyData"
              },
              {
                "$ref": "#/components/schemas/WebhookPromptSuggestionsFailedData"
              },
              {
                "$ref": "#/components/schemas/WebhookTestEventData"
              }
            ]
          }
        }
      },
      "WebhookRunEventData": {
        "type": "object",
        "additionalProperties": false,
        "description": "status is COMPLETED, COMPLETED_WITH_WARNINGS or NO_WORK for\nrun.completed, FAILED with errorCode for run.failed, and CANCELLED for\nrun.cancelled.\n",
        "required": [
          "runId",
          "purpose",
          "status",
          "counts",
          "creditsDebited",
          "createdAt",
          "finalizedAt"
        ],
        "properties": {
          "runId": {
            "type": "string"
          },
          "purpose": {
            "type": "string",
            "enum": [
              "PERIODIC",
              "PROMPT_ADDED",
              "MANUAL",
              "ONBOARDING"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "COMPLETED",
              "COMPLETED_WITH_WARNINGS",
              "NO_WORK",
              "FAILED",
              "CANCELLED"
            ]
          },
          "errorCode": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,63}$",
            "description": "Present on run.failed only"
          },
          "counts": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "requested",
              "completed",
              "failed",
              "skipped",
              "cancelled"
            ],
            "properties": {
              "requested": {
                "type": "integer",
                "minimum": 0
              },
              "completed": {
                "type": "integer",
                "minimum": 0
              },
              "failed": {
                "type": "integer",
                "minimum": 0
              },
              "skipped": {
                "type": "integer",
                "minimum": 0
              },
              "cancelled": {
                "type": "integer",
                "minimum": 0
              }
            }
          },
          "creditsDebited": {
            "type": "integer",
            "minimum": 0
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "finalizedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookPitchAuditCompletedData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "auditId",
          "subjects",
          "creditsDebited",
          "completedAt"
        ],
        "properties": {
          "auditId": {
            "type": "string"
          },
          "subjects": {
            "type": "integer",
            "minimum": 0
          },
          "creditsDebited": {
            "type": "integer",
            "minimum": 0
          },
          "completedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookPitchAuditFailedData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "auditId",
          "errorCode",
          "failedAt"
        ],
        "properties": {
          "auditId": {
            "type": "string"
          },
          "errorCode": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,63}$"
          },
          "failedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookSiteAuditCompletedData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "auditId",
          "counts",
          "createdAt",
          "completedAt"
        ],
        "properties": {
          "auditId": {
            "type": "string"
          },
          "counts": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "total",
              "succeeded",
              "failed",
              "skipped"
            ],
            "properties": {
              "total": {
                "type": "integer",
                "minimum": 0
              },
              "succeeded": {
                "type": "integer",
                "minimum": 0
              },
              "failed": {
                "type": "integer",
                "minimum": 0
              },
              "skipped": {
                "type": "integer",
                "minimum": 0
              }
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "completedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookPromptSuggestionsReadyData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "runId",
          "source",
          "keywordId",
          "recommendations",
          "completedAt"
        ],
        "properties": {
          "runId": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "manual",
              "onboarding",
              "topic",
              "profile"
            ]
          },
          "keywordId": {
            "type": "string",
            "nullable": true
          },
          "recommendations": {
            "type": "integer",
            "minimum": 0,
            "nullable": true,
            "description": "See WebhookEventType for how this value is computed"
          },
          "completedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookPromptSuggestionsFailedData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "runId",
          "source",
          "keywordId",
          "failedAt"
        ],
        "properties": {
          "runId": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "manual",
              "onboarding",
              "topic",
              "profile"
            ]
          },
          "keywordId": {
            "type": "string",
            "nullable": true
          },
          "failedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookTestEventData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "enum": [
              "Test event from Qwairy."
            ]
          }
        }
      },
      "WebhookEndpoint": {
        "type": "object",
        "required": [
          "id",
          "url",
          "events",
          "brandIds",
          "enabled",
          "disabledReason",
          "version",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "The full destination URL. Every key of the team that can read its\nwebhooks, read-only keys included, receives it. A token embedded in\nthe URL (as some automation tools do) is therefore not a secret from\nthose keys: a receiver must verify X-Qwairy-Signature with the\nendpoint secret, and reject unsigned or mis-signed calls.\n"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookEventType"
            }
          },
          "brandIds": {
            "type": "array",
            "description": "Workspaces filtered; empty means every workspace of the team. Team-level events (Pitch Audits, webhook.test) are always delivered.",
            "items": {
              "type": "string"
            }
          },
          "enabled": {
            "type": "boolean"
          },
          "disabledReason": {
            "type": "string",
            "nullable": true,
            "description": "Why the endpoint is disabled. MANUAL: turned off through the API.\nFAILING: its deliveries kept failing for 72 hours. PLAN: the\nteam's plan no longer includes webhooks; enable the endpoint again\nafter upgrading. A past-due payment never disables an endpoint:\nits deliveries, including events that occur meanwhile, wait and\nare sent once the payment succeeds, within the 30-day retention\nof the delivery log.\n",
            "enum": [
              "MANUAL",
              "FAILING",
              "PLAN",
              null
            ]
          },
          "failingSince": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "previousSecretExpiresAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "version": {
            "type": "integer"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookEndpointCreate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "url",
          "events"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "description": "Public https URL."
          },
          "description": {
            "type": "string",
            "maxLength": 200
          },
          "events": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/WebhookEventType"
            }
          },
          "brandIds": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "string"
            }
          },
          "enabled": {
            "type": "boolean",
            "default": true
          }
        }
      },
      "WebhookEndpointWithSecret": {
        "allOf": [
          {
            "$ref": "#/components/schemas/WebhookEndpoint"
          },
          {
            "type": "object",
            "required": [
              "secret"
            ],
            "properties": {
              "secret": {
                "type": "string",
                "description": "Returned only by the creation or rotation response, and by its\nreplay with the same Idempotency-Key within 24 hours. Store it\nto verify signatures.\n"
              }
            }
          }
        ]
      },
      "WebhookEndpointUpdate": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048
          },
          "description": {
            "type": "string",
            "maxLength": 200,
            "nullable": true
          },
          "events": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/WebhookEventType"
            }
          },
          "brandIds": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "string"
            }
          },
          "enabled": {
            "type": "boolean"
          }
        }
      },
      "WebhookDelivery": {
        "type": "object",
        "required": [
          "id",
          "eventId",
          "event",
          "status",
          "attempts",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "eventId": {
            "type": "string"
          },
          "event": {
            "$ref": "#/components/schemas/WebhookEventType"
          },
          "status": {
            "$ref": "#/components/schemas/WebhookDeliveryStatus"
          },
          "attempts": {
            "type": "integer",
            "minimum": 0,
            "maximum": 8
          },
          "nextAttemptAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "lastAttemptAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "lastStatusCode": {
            "type": "integer",
            "nullable": true
          },
          "lastError": {
            "type": "string",
            "nullable": true,
            "enum": [
              "TIMEOUT",
              "CONNECTION",
              "HTTP_STATUS",
              "BLOCKED_TARGET",
              null
            ]
          },
          "deliveredAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookDeliveryStatus": {
        "type": "string",
        "enum": [
          "PENDING",
          "DELIVERING",
          "SUCCEEDED",
          "RETRYING",
          "EXHAUSTED",
          "CANCELLED"
        ]
      },
      "WebhookEventType": {
        "type": "string",
        "description": "run.completed, run.failed and run.cancelled are sent once a run can no\nlonger change. A run that holds a quarantined answer whose provider\npayload can still be replayed (up to 7 days) is reported terminal by\nGET /brands/{brandId}/runs before its event is sent. A delivery is\nattempted at most 8 times: at the start of its cycle, then 1 minute,\n5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours after\nit. A delivery that fell behind (deliveries paused, endpoint\nre-enabled) keeps at least the gap between two of these attempts\nafter its last attempt.\n\nprompt_suggestions.ready carries, in recommendations, the value that\nGET /brands/{brandId}/prompt-suggestions/runs/{suggestionRunId} gave\nfor that generation when the event was recorded: a count, or null\nwhen that endpoint gives none (a profile generation, a pool that is\nnot the newest COMPLETED pool or whose result cannot be read, a topic\ngeneration whose topic was deleted). A topic generation whose topic\nstill exists counts that topic's current share of the pool's\nrecommendations, without its own prompts if its result cannot be\nread: 0 unless the pool already holds a topic of that name. A later\nread of the generation can differ, because tracked prompts,\ncompetitors and newer generations change it; the event is not\nupdated.\n",
        "enum": [
          "run.completed",
          "run.failed",
          "run.cancelled",
          "pitch_audit.completed",
          "pitch_audit.failed",
          "site_audit.completed",
          "prompt_suggestions.ready",
          "prompt_suggestions.failed",
          "webhook.test"
        ]
      },
      "PromptSuggestion": {
        "type": "object",
        "required": [
          "id",
          "text",
          "score",
          "tracked"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Opaque content-bound suggestion ID. Read it again after regeneration; do not construct or parse it."
          },
          "text": {
            "type": "string"
          },
          "topic": {
            "type": "string",
            "nullable": true
          },
          "keywordId": {
            "type": "string",
            "nullable": true,
            "description": "Existing topic id when the suggested topic is already configured."
          },
          "funnelStage": {
            "type": "string",
            "nullable": true
          },
          "intent": {
            "type": "string",
            "nullable": true
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "recommended": {
            "type": "boolean"
          },
          "tracked": {
            "type": "boolean",
            "description": "True when an equivalent prompt is active and monitored. An equivalent archived or paused prompt reads false; accepting the suggestion reactivates it and reports created."
          }
        }
      },
      "PromptSuggestionList": {
        "type": "object",
        "required": [
          "focus",
          "total",
          "suggestions"
        ],
        "properties": {
          "run": {
            "$ref": "#/components/schemas/PromptSuggestionRun"
          },
          "focus": {
            "type": "string"
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of suggestions in the whole pool for this focus, whatever the limit."
          },
          "suggestions": {
            "type": "array",
            "description": "The recommendations first, then the rest of the pool, cut at limit.",
            "items": {
              "$ref": "#/components/schemas/PromptSuggestion"
            }
          }
        }
      },
      "PromptSuggestionRun": {
        "type": "object",
        "required": [
          "id",
          "status",
          "source",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "RUNNING",
              "COMPLETED",
              "FAILED"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "manual",
              "onboarding",
              "topic",
              "profile"
            ]
          },
          "keywordId": {
            "type": "string",
            "nullable": true
          },
          "recommendations": {
            "type": "integer",
            "nullable": true,
            "description": "The recommendations this generation stands for, read from the\nworkspace when requested. For a COMPLETED pool that is still the\nnewest, the Studio recommendations (prompts already tracked are\nleft out, and the workspace's competitors and the per-topic limit\napply), or null if its result cannot be read; for a COMPLETED\ntopic generation whose topic still exists, that topic's current\nshare of the pool's recommendations, without its own prompts if\nits result cannot be read (0 unless the pool already holds a\ntopic of that name); null for any other generation (a profile\ngeneration, a pool that is not the newest COMPLETED pool, a topic\ngeneration whose topic was deleted). The prompt_suggestions.ready\nwebhook event carries the value given when it was recorded.\n"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "completedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "AcceptSuggestionsResult": {
        "type": "object",
        "required": [
          "dryRun",
          "items",
          "dailyCredits"
        ],
        "properties": {
          "dryRun": {
            "type": "boolean"
          },
          "dailyCredits": {
            "type": "number",
            "description": "Average credits per day added by the accepted monitored prompts."
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "suggestionId",
                "outcome"
              ],
              "properties": {
                "suggestionId": {
                  "type": "string"
                },
                "outcome": {
                  "type": "string",
                  "enum": [
                    "created",
                    "already_tracked",
                    "not_found",
                    "invalid"
                  ]
                },
                "promptId": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "AnalyticsResourceNotFound": {
        "description": "Brand is not accessible, or the requested article or completed perception snapshot was not found within the brand",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "RESOURCE_NOT_FOUND",
                "message": "Article not found"
              }
            }
          }
        }
      },
      "WriteUnauthorized": {
        "description": "Missing, invalid or revoked API key on a write command",
        "headers": {
          "X-Request-Id": {
            "description": "Request identifier matching error.requestId in the response body",
            "schema": {
              "type": "string"
            }
          },
          "Cache-Control": {
            "schema": {
              "type": "string",
              "enum": [
                "private, no-store"
              ]
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WriteError"
            },
            "example": {
              "error": {
                "code": "UNAUTHORIZED",
                "message": "Invalid or revoked API key.",
                "requestId": "4f1d0b1e-6c1a-4a2f-9a17-2f2b9a3c4d5e"
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Authentication failed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AuthenticationError"
            },
            "example": {
              "error": "Unauthorized",
              "message": "Invalid API token or insufficient subscription plan (Growth+ required)"
            }
          }
        }
      },
      "InvalidParameter": {
        "description": "Invalid request parameter",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "INVALID_PARAMETER",
                "message": "limit: Maximum limit is 100"
              }
            }
          }
        }
      },
      "InsufficientPlan": {
        "description": "The authenticated team is not entitled to Crawler Analytics",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "INSUFFICIENT_PLAN",
                "message": "Crawler Analytics requires an active Business plan or higher"
              }
            }
          }
        }
      },
      "RateLimitExceeded": {
        "description": "Per-minute or daily team rate limit exceeded",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          },
          "Retry-After": {
            "description": "Seconds before retrying, based on the actual blocking burst or daily window",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RateLimitError"
            },
            "example": {
              "error": "Too Many Requests",
              "limit": "burst",
              "message": "Per-minute rate limit (1000/min) exceeded. Please try again in 12 seconds.",
              "retryAfter": 12
            }
          }
        }
      },
      "BrandNotFound": {
        "description": "Brand not found",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "BRAND_NOT_FOUND",
                "message": "Brand not found or not accessible"
              }
            }
          }
        }
      },
      "CompetitorNotFound": {
        "description": "Brand not accessible (BRAND_NOT_FOUND) or competitor not found (COMPETITOR_NOT_FOUND)",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "COMPETITOR_NOT_FOUND",
                "message": "Competitor not found"
              }
            }
          }
        }
      },
      "SourceNotFound": {
        "description": "Brand not accessible (BRAND_NOT_FOUND) or source not found (SOURCE_NOT_FOUND)",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "SOURCE_NOT_FOUND",
                "message": "Source not found"
              }
            }
          }
        }
      },
      "PromptNotFound": {
        "description": "Brand not accessible (BRAND_NOT_FOUND) or prompt not found (PROMPT_NOT_FOUND)",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "PROMPT_NOT_FOUND",
                "message": "Prompt not found"
              }
            }
          }
        }
      },
      "PitchAuditNotFound": {
        "description": "Pitch Audit not found or owned by another team",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "PITCH_AUDIT_NOT_FOUND",
                "message": "Pitch Audit not found or inaccessible"
              }
            }
          }
        }
      },
      "AnswerNotFound": {
        "description": "Brand not accessible (BRAND_NOT_FOUND) or answer not found (ANSWER_NOT_FOUND)",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ANSWER_NOT_FOUND",
                "message": "Answer not found"
              }
            }
          }
        }
      },
      "WriteForbidden": {
        "description": "The write is refused for this key or team.\nINSUFFICIENT_PLAN: the plan has no write access (writes need an active\nBusiness, Agency Business or Enterprise plan), an explicitly requested\npremium model is not included, a Pitch Audit write comes from a team\nthat is not an agency, or archiving is not available to the team.\nAPI_KEY_READ_ONLY: writes are not enabled on this API key; an Owner or\nManager can enable them in Team Management > REST API. This refusal\ndoes not count against the write quota.",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WriteError"
            },
            "example": {
              "error": {
                "code": "INSUFFICIENT_PLAN",
                "message": "Write endpoints require an active Business, Agency Business or Enterprise plan.",
                "requestId": "4f1d0b1e-6c1a-4a2f-9a17-2f2b9a3c4d5e"
              }
            }
          }
        }
      },
      "WriteConflict": {
        "description": "The request conflicts with the current state. CONFLICT: a duplicate\nor an incompatible state, described in the message.\nIDEMPOTENCY_CONFLICT: the Idempotency-Key was already used with a\ndifferent payload. IDEMPOTENCY_IN_PROGRESS: an earlier request with\nthis key has an unresolved outcome; reconcile the resource state\nbefore starting a new logical operation. INVALID_STATE_TRANSITION: the\nrequested status cannot follow the current one. RESOURCE_BUSY: work in\nprogress prevents the change; retry once it has finished.\nQUOTA_EXCEEDED: a limit is reached: the workspace limit of the plan, a\nPrompt Studio generation allowance (details.resetsAt when known), or\nthe workspace is locked because the team uses more workspaces than its\nplan includes (a locked workspace can only be archived).\nINSUFFICIENT_CREDITS: the balance does not cover the operation.",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WriteError"
            },
            "example": {
              "error": {
                "code": "INVALID_STATE_TRANSITION",
                "message": "A workspace cannot move from LIVE to DRAFT.",
                "requestId": "4f1d0b1e-6c1a-4a2f-9a17-2f2b9a3c4d5e"
              }
            }
          }
        }
      },
      "PreconditionRequired": {
        "description": "If-Match is required for this conditional write",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WriteError"
            }
          }
        }
      },
      "PreconditionFailed": {
        "description": "The resource changed since the ETag you supplied",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WriteError"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "An unexpected server error occurred",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/InternalServerError"
            },
            "example": {
              "error": "Internal Server Error",
              "message": "An unexpected error occurred"
            }
          }
        }
      },
      "WriteUnavailable": {
        "description": "Writes are paused or the write rate limiter is unavailable. Nothing was changed; retry later.",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WriteError"
            },
            "example": {
              "error": {
                "code": "SERVICE_UNAVAILABLE",
                "message": "Writes are temporarily unavailable.",
                "requestId": "4f1d0b1e-6c1a-4a2f-9a17-2f2b9a3c4d5e"
              }
            }
          }
        }
      },
      "WriteInvalidRequest": {
        "description": "INVALID_REQUEST: the body is not valid JSON, or the body, a parameter\nor a header fails validation; details.issues lists up to 10\nproblems. IDEMPOTENCY_KEY_REQUIRED: a POST that requires an\nIdempotency-Key was sent without one.",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WriteError"
            },
            "example": {
              "error": {
                "code": "INVALID_REQUEST",
                "message": "Invalid request payload.",
                "requestId": "4f1d0b1e-6c1a-4a2f-9a17-2f2b9a3c4d5e"
              }
            }
          }
        }
      },
      "WriteNotFound": {
        "description": "The workspace or resource does not exist for this team",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WriteError"
            },
            "example": {
              "error": {
                "code": "RESOURCE_NOT_FOUND",
                "message": "Resource not found.",
                "requestId": "4f1d0b1e-6c1a-4a2f-9a17-2f2b9a3c4d5e"
              }
            }
          }
        }
      },
      "WriteRateLimited": {
        "description": "The team write budget (120 requests per minute and 5,000 per day,\nseparate from reads) is exhausted, or, on POST /brands only, the\nrolling 24-hour workspace creation budget is spent\n(details.reason BRAND_CREATION_DAILY_LIMIT). Nothing was changed.\nRetry after the number of seconds in Retry-After.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WriteError"
            },
            "example": {
              "error": {
                "code": "RATE_LIMIT_EXCEEDED",
                "message": "Rate limit exceeded. Retry in 12 seconds.",
                "requestId": "4f1d0b1e-6c1a-4a2f-9a17-2f2b9a3c4d5e"
              }
            }
          }
        }
      },
      "WriteRequestTooLarge": {
        "description": "The JSON body exceeds the resource limits (size, nesting, array or\nobject sizes) shared by the authenticated API surfaces. Nothing was\nchanged.",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WriteError"
            },
            "example": {
              "error": {
                "code": "INVALID_REQUEST",
                "message": "Request body exceeds resource limits.",
                "requestId": "4f1d0b1e-6c1a-4a2f-9a17-2f2b9a3c4d5e"
              }
            }
          }
        }
      },
      "WriteInternalError": {
        "description": "An unexpected error occurred. If it happened after the command\nstarted, its outcome is unknown: a POST retried with the same\nIdempotency-Key returns 409 IDEMPOTENCY_IN_PROGRESS. Reconcile the\nresource state before starting a new logical operation.",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WriteError"
            },
            "example": {
              "error": {
                "code": "INTERNAL_ERROR",
                "message": "An unexpected error occurred.",
                "requestId": "4f1d0b1e-6c1a-4a2f-9a17-2f2b9a3c4d5e"
              }
            }
          }
        }
      },
      "ApiPlanRequired": {
        "description": "The team plan does not include this API surface",
        "headers": {
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitBurstLimit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitBurstRemaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitBurstReset"
          },
          "X-RateLimit-Daily-Limit": {
            "$ref": "#/components/headers/RateLimitDailyLimit"
          },
          "X-RateLimit-Daily-Remaining": {
            "$ref": "#/components/headers/RateLimitDailyRemaining"
          },
          "X-RateLimit-Daily-Reset": {
            "$ref": "#/components/headers/RateLimitDailyReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "INSUFFICIENT_PLAN",
                "message": "This endpoint is not included in the team's plan."
              }
            }
          }
        }
      }
    },
    "headers": {
      "ETag": {
        "description": "Version of the returned resource. Qwairy emits the strong form, such\nas \"7\"; a response compressed in transit can carry the weak form W/\"7\"\nof the same version. Send either form back unchanged in If-Match: both\npin the same version.",
        "schema": {
          "type": "string",
          "example": "\"7\""
        }
      },
      "Location": {
        "description": "URL of the created or accepted resource.",
        "schema": {
          "type": "string"
        }
      },
      "RateLimitPolicy": {
        "description": "Checked team quotas as a Structured Fields list of strings with q (requests) and w (seconds). Follows draft-ietf-httpapi-ratelimit-headers-11 section 3, not a final RFC. Present only after a completed authenticated rate-limit check; team overrides apply. Uses the read or separate write budget checked for this operation; omitted before the limiter is reached.",
        "schema": {
          "type": "string",
          "example": "\"burst\";q=1000;w=60, \"daily\";q=20000;w=86400"
        }
      },
      "RateLimit": {
        "description": "Checked remaining quotas as a Structured Fields list of strings with r (requests) and t (non-negative integer delta-seconds until the end of the current effective window, never a date). This limiter window hint does not guarantee complete quota renewal at its end. Follows draft-ietf-httpapi-ratelimit-headers-11 section 4, not a final RFC. Present only after a completed authenticated rate-limit check, including errors after consumption. Uses the read or separate write budget checked for this operation; omitted before the limiter is reached.",
        "schema": {
          "type": "string",
          "example": "\"burst\";r=999;t=60, \"daily\";r=19999;t=86400"
        }
      },
      "RateLimitBurstLimit": {
        "description": "Legacy checked per-minute request quota. May contain zero values after a limiter timeout; use the standard fields for verified quotas. Uses the read or separate write budget checked for this operation; omitted before the limiter is reached.",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "example": 1000
        }
      },
      "RateLimitBurstRemaining": {
        "description": "Legacy remaining per-minute requests. May contain zero values after a limiter timeout; use the standard fields for verified quotas. Uses the read or separate write budget checked for this operation; omitted before the limiter is reached.",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "example": 999
        }
      },
      "RateLimitBurstReset": {
        "description": "Legacy per-minute reset as an absolute ISO 8601 timestamp. May contain the Unix epoch after a limiter timeout; use the standard fields for verified quotas. Uses the read or separate write budget checked for this operation; omitted before the limiter is reached.",
        "schema": {
          "type": "string",
          "format": "date-time",
          "example": "2026-10-24T12:01:00.000Z"
        }
      },
      "RateLimitDailyLimit": {
        "description": "Legacy checked daily request quota. May contain zero values after a limiter timeout; use the standard fields for verified quotas. Uses the read or separate write budget checked for this operation; omitted before the limiter is reached.",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "example": 20000
        }
      },
      "RateLimitDailyRemaining": {
        "description": "Legacy remaining daily requests. May contain zero values after a limiter timeout; use the standard fields for verified quotas. Uses the read or separate write budget checked for this operation; omitted before the limiter is reached.",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "example": 19999
        }
      },
      "RateLimitDailyReset": {
        "description": "Legacy daily reset as an absolute ISO 8601 timestamp. May contain the Unix epoch after a limiter timeout; use the standard fields for verified quotas. Uses the read or separate write budget checked for this operation; omitted before the limiter is reached.",
        "schema": {
          "type": "string",
          "format": "date-time",
          "example": "2026-10-25T12:00:00.000Z"
        }
      }
    }
  }
}
