{
  "openapi": "3.0.0",
  "info": {
    "title": "Omnia API",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://app.useomnia.com",
      "description": "Omnia API Server"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Brand"
    },
    {
      "name": "Brand Performance",
      "x-displayName": "Performance"
    },
    {
      "name": "Topic"
    },
    {
      "name": "Topic Performance",
      "x-displayName": "Performance"
    },
    {
      "name": "Prompt"
    },
    {
      "name": "Prompt Performance",
      "x-displayName": "Performance"
    },
    {
      "name": "AI Answer"
    },
    {
      "name": "Trend"
    },
    {
      "name": "Insight"
    },
    {
      "name": "Insight Generation",
      "x-displayName": "Generation"
    },
    {
      "name": "Project"
    },
    {
      "name": "View"
    },
    {
      "name": "View Performance",
      "x-displayName": "Performance"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API token authentication. Use format: Bearer ot_your-token-here"
      }
    },
    "schemas": {
      "Pagination": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "minimum": 1,
            "description": "Current page number",
            "example": 1
          },
          "pageSize": {
            "type": "integer",
            "minimum": 5,
            "maximum": 100,
            "description": "Number of items per page",
            "example": 10
          },
          "totalItems": {
            "type": "integer",
            "minimum": 0,
            "description": "Total number of items across all pages",
            "example": 420
          }
        },
        "required": [
          "page",
          "pageSize",
          "totalItems"
        ],
        "description": "Pagination metadata for list responses"
      },
      "Links": {
        "type": "object",
        "properties": {
          "prev": {
            "type": "string",
            "format": "uri",
            "description": "URL to fetch the previous page of results, null if on first page",
            "example": "https://app.useomnia.com/api/v1/resource?page=1&pageSize=10"
          },
          "next": {
            "type": "string",
            "format": "uri",
            "description": "URL to fetch the next page of results, null if on last page",
            "example": "https://app.useomnia.com/api/v1/resource?page=3&pageSize=10"
          }
        },
        "description": "Navigation links for paginated responses"
      },
      "AiAnswerListItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "Unique identifier for this AI answer instance",
            "example": 12345
          },
          "engine": {
            "type": "string",
            "enum": [
              "google-ai-overviews",
              "google-ai-mode",
              "perplexity",
              "openai",
              "gemini",
              "grok",
              "copilot",
              "claude"
            ],
            "description": "AI engine that generated this response",
            "example": "openai"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 date-time string indicating when this answer was captured",
            "example": "2026-01-01T09:30:00Z"
          },
          "hasAnswer": {
            "type": "boolean",
            "description": "Indicates whether the engine returned a non-empty answer text",
            "example": true
          },
          "domains": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of unique domains cited or referenced in this answer",
            "example": [
              "acme.com",
              "example.com"
            ]
          },
          "shareOfVoice": {
            "type": "number",
            "description": "Percentage of citation presence for the tracked brand within this answer (0-1). Calculated from citation count relative to total citations in the response",
            "example": 0.25
          },
          "mentioned": {
            "type": "boolean",
            "description": "Whether the tracked brand was explicitly mentioned in this answer",
            "example": true
          },
          "mentionedBrands": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "All brand names detected in this answer, including competitors",
            "example": [
              "Brand 1",
              "Brand 2",
              "Brand 3"
            ]
          },
          "sentiment": {
            "type": "object",
            "properties": {
              "endorsed": {
                "type": "number",
                "description": "Number of features where the tracked brand is positively positioned",
                "example": 2
              },
              "undermined": {
                "type": "number",
                "description": "Number of features where the tracked brand is negatively positioned",
                "example": 1
              },
              "neutral": {
                "type": "number",
                "description": "Number of features where the tracked brand is neutrally positioned",
                "example": 3
              }
            },
            "required": [
              "endorsed",
              "undermined",
              "neutral"
            ],
            "description": "Sentiment breakdown for the tracked brand in this answer. Present when the brand is mentioned with feature-level analysis"
          }
        },
        "required": [
          "id",
          "engine",
          "createdAt",
          "hasAnswer",
          "domains",
          "shareOfVoice",
          "mentioned",
          "mentionedBrands"
        ]
      },
      "AiAnswerBrandFilterOption": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "description": "Primary domain of the brand",
            "example": "acme.com"
          },
          "name": {
            "type": "string",
            "description": "Display name of the brand",
            "example": "Acme Corporation"
          }
        },
        "required": [
          "domain",
          "name"
        ]
      },
      "AiAnswerFeatureOption": {
        "type": "object",
        "properties": {
          "featureName": {
            "type": "string",
            "description": "Normalized feature name",
            "example": "pricing"
          },
          "brands": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Normalized brand names associated with this feature in the current result set",
            "example": [
              "acme",
              "competitor"
            ]
          }
        },
        "required": [
          "featureName",
          "brands"
        ]
      },
      "AiAnswerFilterOptions": {
        "type": "object",
        "properties": {
          "availableBrands": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/AiAnswerBrandFilterOption"
            },
            "description": "Map of normalized brand name to brand details, available for filtering"
          },
          "availableCitations": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of citation domains found in the current result set",
            "example": [
              "acme.com",
              "example.com"
            ]
          },
          "availableFeatures": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AiAnswerFeatureOption"
            },
            "description": "Features found in the current result set, each with associated brands. Use these values for the featureAttribution filter parameter"
          }
        },
        "required": [
          "availableBrands",
          "availableCitations",
          "availableFeatures"
        ],
        "description": "Available filter values computed from the current result set. Use these to build filter UIs or discover valid filter parameters"
      },
      "AiAnswersData": {
        "type": "object",
        "properties": {
          "answers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AiAnswerListItem"
            },
            "description": "Array of AI answer instances for the specified prompt"
          },
          "filterOptions": {
            "$ref": "#/components/schemas/AiAnswerFilterOptions"
          }
        },
        "required": [
          "answers",
          "filterOptions"
        ]
      },
      "PaginatedResponse": {
        "type": "object",
        "properties": {
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "links": {
            "$ref": "#/components/schemas/Links"
          }
        },
        "required": [
          "pagination",
          "links"
        ],
        "description": "Base schema for paginated responses"
      },
      "AiAnswersListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaginatedResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/AiAnswersData"
              }
            },
            "required": [
              "data"
            ]
          }
        ],
        "description": "Paginated response containing AI answer history for a specific prompt"
      },
      "Citation": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Page title of the cited source",
            "example": "Best Software 2026 | Acme Reviews"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "URL of the cited source",
            "example": "https://example.com/software-reviews"
          }
        },
        "required": [
          "url"
        ]
      },
      "AiAnswer": {
        "type": "object",
        "properties": {
          "answer": {
            "type": "string",
            "description": "Full text of the AI-generated response",
            "example": "Based on my analysis, the best software for small businesses includes Brand 1, Brand 2, and Brand 3..."
          },
          "citations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Citation"
            },
            "description": "Sources referenced by the AI engine in its response"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp when the response was captured",
            "example": "2026-01-01T09:30:00Z"
          },
          "engine": {
            "type": "string",
            "enum": [
              "google-ai-overviews",
              "google-ai-mode",
              "perplexity",
              "openai",
              "gemini",
              "grok",
              "copilot",
              "claude"
            ],
            "description": "AI engine that generated this response",
            "example": "openai"
          },
          "id": {
            "type": "number",
            "description": "Unique identifier for this AI answer",
            "example": 12345
          },
          "mentioned": {
            "type": "boolean",
            "description": "Whether your brand was mentioned in the response",
            "example": true
          },
          "mentionedBrands": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Brand names detected in the response text",
            "example": [
              "Brand 1",
              "Brand 2",
              "Brand 3"
            ]
          },
          "promptId": {
            "type": "string",
            "format": "uuid",
            "description": "Identifier of the prompt that triggered this response",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "query": {
            "type": "string",
            "description": "The prompt text sent to the AI engine",
            "example": "What is the best software for small businesses?"
          }
        },
        "required": [
          "answer",
          "citations",
          "createdAt",
          "engine",
          "id",
          "mentioned",
          "mentionedBrands",
          "promptId",
          "query"
        ]
      },
      "AiAnswerResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/AiAnswer"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing a single AI answer"
      },
      "Brand": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the brand",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "name": {
            "type": "string",
            "description": "Display name of the brand as it appears in AI engine responses",
            "example": "Acme Corporation"
          },
          "domain": {
            "type": "string",
            "description": "Primary website domain associated with this brand, used for citation matching",
            "example": "acme.com"
          },
          "slug": {
            "type": "string",
            "description": "URL-friendly identifier for the brand, derived from the domain",
            "example": "acme"
          },
          "mainLocation": {
            "type": "string",
            "nullable": true,
            "description": "ISO 3166-1 alpha-2 country code representing the brand's primary market. Used as default location filter when querying brand data",
            "example": "us",
            "deprecated": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp indicating when the brand was created",
            "example": "2026-01-01T09:30:00Z"
          },
          "setupCompletedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time",
            "description": "ISO 8601 timestamp indicating when Brand setup was completed. Null means setup is unfinished.",
            "example": "2026-01-01T09:30:00Z"
          }
        },
        "required": [
          "id",
          "name",
          "domain",
          "slug",
          "createdAt",
          "setupCompletedAt"
        ],
        "description": "A user tracked brand"
      },
      "BrandsListResponseData": {
        "type": "object",
        "properties": {
          "brands": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Brand"
            },
            "description": "Array of brand objects belonging to the authenticated organization"
          }
        },
        "required": [
          "brands"
        ]
      },
      "BrandsListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaginatedResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/BrandsListResponseData"
              }
            },
            "required": [
              "data"
            ]
          }
        ],
        "description": "Paginated response containing the list of brands"
      },
      "CreateBrandResponse": {
        "type": "object",
        "properties": {
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Brand"
              },
              {
                "description": "The newly created brand object"
              }
            ]
          }
        },
        "required": [
          "data"
        ],
        "description": "Response after successfully creating a brand"
      },
      "CreateBrandBody": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "Display name of the brand as it appears in AI engine responses",
            "example": "Acme Corporation"
          },
          "domain": {
            "type": "string",
            "description": "Primary website domain associated with this brand, used for citation matching",
            "example": "acme.com"
          },
          "alternativeNames": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Alternative names or aliases for this brand that should also be tracked",
            "example": [
              "Acme",
              "Acme Inc"
            ]
          },
          "overview": {
            "type": "string",
            "description": "Brief description or overview of the brand",
            "example": "A leading technology company specializing in cloud solutions"
          },
          "productsAndServices": {
            "type": "string",
            "description": "Description of the products and services offered by the brand",
            "example": "Cloud computing, AI solutions, enterprise software"
          },
          "markets": {
            "type": "string",
            "description": "Target markets or industries the brand operates in",
            "example": "Enterprise, SMB, Government"
          },
          "competitors": {
            "type": "string",
            "description": "Known competitors of this brand",
            "example": "Competitor A, Competitor B"
          }
        },
        "required": [
          "name",
          "domain"
        ],
        "description": "Request body for creating a new brand"
      },
      "BrandResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Brand"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing a single brand"
      },
      "UpdateBrandBody": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "Display name of the brand as it appears in AI engine responses",
            "example": "Acme Corporation"
          },
          "domain": {
            "type": "string",
            "description": "Primary website domain associated with this brand, used for citation matching",
            "example": "acme.com"
          },
          "alternativeNames": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Alternative names or aliases for this brand that should also be tracked",
            "example": [
              "Acme",
              "Acme Inc"
            ]
          },
          "overview": {
            "type": "string",
            "description": "Brief description or overview of the brand",
            "example": "A leading technology company specializing in cloud solutions"
          },
          "productsAndServices": {
            "type": "string",
            "description": "Description of the products and services offered by the brand",
            "example": "Cloud computing, AI solutions, enterprise software"
          },
          "markets": {
            "type": "string",
            "description": "Target markets or industries the brand operates in",
            "example": "Enterprise, SMB, Government"
          },
          "competitors": {
            "type": "string",
            "description": "Known competitors of this brand",
            "example": "Competitor A, Competitor B"
          }
        },
        "description": "Request body for updating a brand"
      },
      "ShareOfVoice": {
        "type": "object",
        "properties": {
          "brand": {
            "type": "string",
            "description": "Name of the brand",
            "example": "Acme Corporation"
          },
          "domain": {
            "type": "string",
            "description": "Primary domain associated with the brand",
            "example": "acme.com"
          },
          "mentionCount": {
            "type": "number",
            "nullable": true,
            "description": "Total number of times this brand was mentioned by AI engines",
            "example": 150
          },
          "rank": {
            "type": "number",
            "nullable": true,
            "description": "Brand's position in share of voice ranking, null if not ranked",
            "example": 3
          },
          "relationship": {
            "type": "string",
            "enum": [
              "owned",
              "competitor"
            ],
            "description": "Whether this is your brand or a competitor",
            "example": "owned"
          },
          "shareOfVoice": {
            "type": "number",
            "description": "Percentage of total AI mentions attributed to this brand (0-1)",
            "example": 0.25
          }
        },
        "required": [
          "brand",
          "domain",
          "mentionCount",
          "rank",
          "relationship",
          "shareOfVoice"
        ]
      },
      "ShareOfVoiceAggregatesData": {
        "type": "object",
        "properties": {
          "aggregates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShareOfVoice"
            },
            "description": "List of share of voice data per brand"
          }
        },
        "required": [
          "aggregates"
        ]
      },
      "ShareOfVoiceAggregatesResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaginatedResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/ShareOfVoiceAggregatesData"
              }
            },
            "required": [
              "data"
            ]
          }
        ],
        "description": "Paginated response containing share of voice aggregates"
      },
      "TimeSeries": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Name of the brand",
            "example": "Acme Corporation"
          },
          "domain": {
            "type": "string",
            "description": "Primary domain associated with the brand",
            "example": "acme.com"
          },
          "rank": {
            "type": "number",
            "nullable": true,
            "description": "Brand's position in this ranking, null if not ranked",
            "example": 3
          },
          "relationship": {
            "type": "string",
            "enum": [
              "owned",
              "competitor"
            ],
            "description": "Whether this is your brand or a competitor",
            "example": "owned"
          },
          "points": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "format": "date",
                  "description": "Date of the time series data point",
                  "example": "2026-01-01"
                },
                "value": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1,
                  "description": "Time series value at this date (0-1), undefined if no data available for this date",
                  "example": 0.25
                }
              },
              "required": [
                "date"
              ]
            },
            "description": "Time series data points with values over time"
          }
        },
        "required": [
          "label",
          "domain",
          "rank",
          "relationship",
          "points"
        ]
      },
      "TimeSeriesData": {
        "type": "object",
        "properties": {
          "timeSeries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TimeSeries"
            },
            "description": "List of time series data"
          }
        },
        "required": [
          "timeSeries"
        ]
      },
      "BrandShareOfVoiceTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/TimeSeriesData"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing all points in the requested time series"
      },
      "VisibilityAggregates": {
        "type": "object",
        "properties": {
          "brand": {
            "type": "string",
            "description": "Name of the brand",
            "example": "Acme Corporation"
          },
          "domain": {
            "type": "string",
            "description": "Primary domain associated with the brand",
            "example": "acme.com"
          },
          "rank": {
            "type": "number",
            "nullable": true,
            "description": "Brand's position in visibility ranking, null if not ranked",
            "example": 3
          },
          "relationship": {
            "type": "string",
            "enum": [
              "owned",
              "competitor"
            ],
            "description": "Whether this is your brand or a competitor",
            "example": "owned"
          },
          "visibility": {
            "type": "number",
            "nullable": true,
            "description": "Visibility score combining mentions and citations (0-1)",
            "example": 0.25
          }
        },
        "required": [
          "brand",
          "domain",
          "rank",
          "relationship",
          "visibility"
        ]
      },
      "VisibilityAggregatesData": {
        "type": "object",
        "properties": {
          "aggregates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VisibilityAggregates"
            },
            "description": "List of visibility data per brand"
          }
        },
        "required": [
          "aggregates"
        ]
      },
      "VisibilityAggregatesResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaginatedResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/VisibilityAggregatesData"
              }
            },
            "required": [
              "data"
            ]
          }
        ],
        "description": "Paginated response containing visibility aggregates"
      },
      "BrandVisibilityTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/TimeSeriesData"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing all points in the requested time series"
      },
      "CitationsAggregates": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "description": "Domain of the cited source",
            "example": "example.com"
          },
          "shareOfVoice": {
            "type": "number",
            "description": "Percentage of total citations this source represents (0-1)",
            "example": 0.25
          },
          "title": {
            "type": "string",
            "description": "Page title of the cited source",
            "example": "Best Software Reviews 2026"
          },
          "totalCitations": {
            "type": "number",
            "description": "Number of times this source was cited by AI engines",
            "example": 42
          },
          "type": {
            "type": "string",
            "enum": [
              "owned",
              "third_party",
              "social"
            ],
            "description": "Ownership relationship to the cited source",
            "example": "owned"
          },
          "url": {
            "type": "string",
            "description": "Full URL of the cited page",
            "example": "https://example.com/reviews"
          }
        },
        "required": [
          "domain",
          "shareOfVoice",
          "totalCitations",
          "type",
          "url"
        ]
      },
      "CitationsAggregatesData": {
        "type": "object",
        "properties": {
          "aggregates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CitationsAggregates"
            },
            "description": "List of citation aggregates for the brand"
          }
        },
        "required": [
          "aggregates"
        ]
      },
      "CitationsAggregatesResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaginatedResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/CitationsAggregatesData"
              }
            },
            "required": [
              "data"
            ]
          }
        ],
        "description": "Paginated response containing citation aggregates"
      },
      "BrandCitationsTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/TimeSeriesData"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing all points in the requested time series"
      },
      "SentimentTimeSeriesPoint": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "description": "Date of the data point",
            "example": "2026-01-01"
          },
          "endorsedMentions": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of endorsed (positive) feature mentions on this date",
            "example": 12
          },
          "underminedMentions": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of undermined (negative) feature mentions on this date",
            "example": 3
          },
          "neutralMentions": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of neutral feature mentions on this date",
            "example": 8
          }
        },
        "required": [
          "date",
          "endorsedMentions",
          "underminedMentions",
          "neutralMentions"
        ]
      },
      "SentimentTimeSeriesData": {
        "type": "object",
        "properties": {
          "timeSeries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SentimentTimeSeriesPoint"
            },
            "description": "Daily sentiment distribution data points"
          }
        },
        "required": [
          "timeSeries"
        ]
      },
      "BrandSentimentTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/SentimentTimeSeriesData"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing daily sentiment feature mention distribution for a brand"
      },
      "SentimentAggregate": {
        "type": "object",
        "properties": {
          "brand": {
            "type": "string",
            "description": "Name of the brand",
            "example": "Acme Corporation"
          },
          "domain": {
            "type": "string",
            "description": "Primary domain associated with the brand",
            "example": "acme.com"
          },
          "relationship": {
            "type": "string",
            "enum": [
              "owned",
              "competitor"
            ],
            "description": "Whether this is your brand or a competitor",
            "example": "owned"
          },
          "rank": {
            "type": "integer",
            "minimum": 1,
            "description": "Brand's position in sentiment ranking",
            "example": 1
          },
          "featureName": {
            "type": "string",
            "description": "Name of the feature",
            "example": "customer support"
          },
          "featureDescription": {
            "type": "string",
            "description": "Description of what this feature represents",
            "example": "Quality and responsiveness of customer support"
          },
          "endorsedMentions": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of endorsed (positive) feature mentions",
            "example": 8
          },
          "underminedMentions": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of undermined (negative) feature mentions",
            "example": 2
          },
          "neutralMentions": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of neutral feature mentions",
            "example": 4
          },
          "totalMentions": {
            "type": "integer",
            "minimum": 0,
            "description": "Total number of feature mentions for this brand-feature pair",
            "example": 14
          }
        },
        "required": [
          "brand",
          "domain",
          "relationship",
          "rank",
          "featureName",
          "featureDescription",
          "endorsedMentions",
          "underminedMentions",
          "neutralMentions",
          "totalMentions"
        ]
      },
      "SentimentAggregatesData": {
        "type": "object",
        "properties": {
          "aggregates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SentimentAggregate"
            },
            "description": "Flat list of brand-feature sentiment aggregates"
          }
        },
        "required": [
          "aggregates"
        ]
      },
      "SentimentAggregatesResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaginatedResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/SentimentAggregatesData"
              }
            },
            "required": [
              "data"
            ]
          }
        ],
        "description": "Paginated response containing flat sentiment aggregates (one row per brand-feature pair)"
      },
      "ExportBrandShareOfVoiceRow": {
        "type": "object",
        "properties": {
          "brandId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the brand the export was requested for",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "brandName": {
            "type": "string",
            "description": "Name of the brand the export was requested for",
            "example": "Acme Corporation"
          },
          "brandDomain": {
            "type": "string",
            "description": "Domain of the brand the export was requested for",
            "example": "acme.com"
          },
          "date": {
            "type": "string",
            "description": "Day the row covers, formatted as `YYYY-MM-DD`",
            "example": "2026-01-01"
          },
          "rank": {
            "type": "number",
            "nullable": true,
            "description": "Ranking of the brand within the partition, or `null` when not applicable",
            "example": 3
          },
          "relationship": {
            "type": "string",
            "enum": [
              "owned",
              "competitor"
            ],
            "description": "Whether the row belongs to the owned brand (`owned`) or to a competing brand (`competitor`)"
          },
          "row": {
            "type": "integer",
            "description": "Stable ordering index across the whole response",
            "example": 1
          },
          "brand": {
            "type": "string",
            "description": "Name of the brand (owned or competitor) the row reports on",
            "example": "Acme Corporation"
          },
          "domain": {
            "type": "string",
            "description": "Domain of the brand (owned or competitor) the row reports on",
            "example": "acme.com"
          },
          "mentionCount": {
            "type": "integer",
            "description": "Number of times the brand was mentioned",
            "example": 12
          },
          "shareOfVoice": {
            "type": "number",
            "description": "Share of voice of the brand (0-1 scale)",
            "example": 0.25
          },
          "engine": {
            "type": "string",
            "enum": [
              "google-ai-overviews",
              "google-ai-mode",
              "perplexity",
              "openai",
              "gemini",
              "grok",
              "copilot",
              "claude"
            ],
            "description": "AI engine the row was observed on",
            "example": "openai"
          }
        },
        "required": [
          "brandId",
          "brandName",
          "brandDomain",
          "date",
          "rank",
          "relationship",
          "row",
          "brand",
          "domain",
          "mentionCount",
          "shareOfVoice",
          "engine"
        ],
        "description": "Brand-level share of voice export row"
      },
      "ExportBrandVisibilityRow": {
        "type": "object",
        "properties": {
          "brandId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the brand the export was requested for",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "brandName": {
            "type": "string",
            "description": "Name of the brand the export was requested for",
            "example": "Acme Corporation"
          },
          "brandDomain": {
            "type": "string",
            "description": "Domain of the brand the export was requested for",
            "example": "acme.com"
          },
          "date": {
            "type": "string",
            "description": "Day the row covers, formatted as `YYYY-MM-DD`",
            "example": "2026-01-01"
          },
          "rank": {
            "type": "number",
            "nullable": true,
            "description": "Ranking of the brand within the partition, or `null` when not applicable",
            "example": 3
          },
          "relationship": {
            "type": "string",
            "enum": [
              "owned",
              "competitor"
            ],
            "description": "Whether the row belongs to the owned brand (`owned`) or to a competing brand (`competitor`)"
          },
          "row": {
            "type": "integer",
            "description": "Stable ordering index across the whole response",
            "example": 1
          },
          "brand": {
            "type": "string",
            "description": "Name of the brand (owned or competitor) the row reports on",
            "example": "Acme Corporation"
          },
          "domain": {
            "type": "string",
            "description": "Domain of the brand (owned or competitor) the row reports on",
            "example": "acme.com"
          },
          "visibility": {
            "type": "number",
            "description": "Visibility of the brand (0-1 scale)",
            "example": 0.25
          },
          "engine": {
            "type": "string",
            "enum": [
              "google-ai-overviews",
              "google-ai-mode",
              "perplexity",
              "openai",
              "gemini",
              "grok",
              "copilot",
              "claude"
            ],
            "description": "AI engine the row was observed on",
            "example": "openai"
          }
        },
        "required": [
          "brandId",
          "brandName",
          "brandDomain",
          "date",
          "rank",
          "relationship",
          "row",
          "brand",
          "domain",
          "visibility",
          "engine"
        ],
        "description": "Brand-level visibility export row"
      },
      "ExportBrandCitationsRow": {
        "type": "object",
        "properties": {
          "brandId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the brand the export was requested for",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "brandName": {
            "type": "string",
            "description": "Name of the brand the export was requested for",
            "example": "Acme Corporation"
          },
          "brandDomain": {
            "type": "string",
            "description": "Domain of the brand the export was requested for",
            "example": "acme.com"
          },
          "date": {
            "type": "string",
            "description": "Day the row covers, formatted as `YYYY-MM-DD`",
            "example": "2026-01-01"
          },
          "rank": {
            "type": "number",
            "nullable": true,
            "description": "Ranking of the brand within the partition, or `null` when not applicable",
            "example": 3
          },
          "relationship": {
            "type": "string",
            "enum": [
              "owned",
              "competitor"
            ],
            "description": "Whether the row belongs to the owned brand (`owned`) or to a competing brand (`competitor`)"
          },
          "row": {
            "type": "integer",
            "description": "Stable ordering index across the whole response",
            "example": 1
          },
          "citedDomain": {
            "type": "string",
            "description": "Domain of the cited source",
            "example": "example.com"
          },
          "citedUrl": {
            "type": "string",
            "description": "URL of the cited source",
            "example": "https://example.com/reviews"
          },
          "citedTitle": {
            "type": "string",
            "nullable": true,
            "description": "Title of the cited source, if available",
            "example": "Best project management tools of 2026"
          },
          "totalCitations": {
            "type": "integer",
            "description": "Total number of citations the source received",
            "example": 7
          },
          "shareOfVoice": {
            "type": "number",
            "description": "Share of voice attributed to the cited source (0-1 scale)",
            "example": 0.25
          },
          "engine": {
            "type": "string",
            "enum": [
              "google-ai-overviews",
              "google-ai-mode",
              "perplexity",
              "openai",
              "gemini",
              "grok",
              "copilot",
              "claude"
            ],
            "description": "AI engine the row was observed on",
            "example": "openai"
          }
        },
        "required": [
          "brandId",
          "brandName",
          "brandDomain",
          "date",
          "rank",
          "relationship",
          "row",
          "citedDomain",
          "citedUrl",
          "totalCitations",
          "shareOfVoice",
          "engine"
        ],
        "description": "Brand-level citations export row"
      },
      "ExportTopicShareOfVoiceRow": {
        "type": "object",
        "properties": {
          "brandId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the brand the export was requested for",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "brandName": {
            "type": "string",
            "description": "Name of the brand the export was requested for",
            "example": "Acme Corporation"
          },
          "brandDomain": {
            "type": "string",
            "description": "Domain of the brand the export was requested for",
            "example": "acme.com"
          },
          "topicId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the topic the row belongs to",
            "example": "550e8400-e29b-41d4-a716-446655440001"
          },
          "topicName": {
            "type": "string",
            "description": "Name of the topic the row belongs to",
            "example": "project management software"
          },
          "topicType": {
            "type": "string",
            "nullable": true,
            "description": "Type of the topic (e.g. category) or `null` if not set"
          },
          "topicLocation": {
            "type": "string",
            "nullable": true,
            "description": "Location (country code) the topic is monitored for",
            "example": "us"
          },
          "topicTags": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Tags associated with the topic, or `null` if the topic has no tags",
            "example": [
              "product",
              "high-priority"
            ]
          },
          "date": {
            "type": "string",
            "description": "Day the row covers, formatted as `YYYY-MM-DD`",
            "example": "2026-01-01"
          },
          "rank": {
            "type": "number",
            "nullable": true,
            "description": "Ranking of the brand within the partition, or `null` when not applicable",
            "example": 3
          },
          "relationship": {
            "type": "string",
            "enum": [
              "owned",
              "competitor"
            ],
            "description": "Whether the row belongs to the owned brand (`owned`) or to a competing brand (`competitor`)"
          },
          "row": {
            "type": "integer",
            "description": "Stable ordering index across the whole response",
            "example": 1
          },
          "brand": {
            "type": "string",
            "description": "Name of the brand (owned or competitor) the row reports on",
            "example": "Acme Corporation"
          },
          "domain": {
            "type": "string",
            "description": "Domain of the brand (owned or competitor) the row reports on",
            "example": "acme.com"
          },
          "mentionCount": {
            "type": "integer",
            "description": "Number of times the brand was mentioned",
            "example": 12
          },
          "shareOfVoice": {
            "type": "number",
            "description": "Share of voice of the brand (0-1 scale)",
            "example": 0.25
          },
          "engine": {
            "type": "string",
            "enum": [
              "google-ai-overviews",
              "google-ai-mode",
              "perplexity",
              "openai",
              "gemini",
              "grok",
              "copilot",
              "claude"
            ],
            "description": "AI engine the row was observed on",
            "example": "openai"
          }
        },
        "required": [
          "brandId",
          "brandName",
          "brandDomain",
          "topicId",
          "topicName",
          "topicType",
          "topicLocation",
          "topicTags",
          "date",
          "rank",
          "relationship",
          "row",
          "brand",
          "domain",
          "mentionCount",
          "shareOfVoice",
          "engine"
        ],
        "description": "Topic-level share of voice export row"
      },
      "ExportTopicVisibilityRow": {
        "type": "object",
        "properties": {
          "brandId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the brand the export was requested for",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "brandName": {
            "type": "string",
            "description": "Name of the brand the export was requested for",
            "example": "Acme Corporation"
          },
          "brandDomain": {
            "type": "string",
            "description": "Domain of the brand the export was requested for",
            "example": "acme.com"
          },
          "topicId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the topic the row belongs to",
            "example": "550e8400-e29b-41d4-a716-446655440001"
          },
          "topicName": {
            "type": "string",
            "description": "Name of the topic the row belongs to",
            "example": "project management software"
          },
          "topicType": {
            "type": "string",
            "nullable": true,
            "description": "Type of the topic (e.g. category) or `null` if not set"
          },
          "topicLocation": {
            "type": "string",
            "nullable": true,
            "description": "Location (country code) the topic is monitored for",
            "example": "us"
          },
          "topicTags": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Tags associated with the topic, or `null` if the topic has no tags",
            "example": [
              "product",
              "high-priority"
            ]
          },
          "date": {
            "type": "string",
            "description": "Day the row covers, formatted as `YYYY-MM-DD`",
            "example": "2026-01-01"
          },
          "rank": {
            "type": "number",
            "nullable": true,
            "description": "Ranking of the brand within the partition, or `null` when not applicable",
            "example": 3
          },
          "relationship": {
            "type": "string",
            "enum": [
              "owned",
              "competitor"
            ],
            "description": "Whether the row belongs to the owned brand (`owned`) or to a competing brand (`competitor`)"
          },
          "row": {
            "type": "integer",
            "description": "Stable ordering index across the whole response",
            "example": 1
          },
          "brand": {
            "type": "string",
            "description": "Name of the brand (owned or competitor) the row reports on",
            "example": "Acme Corporation"
          },
          "domain": {
            "type": "string",
            "description": "Domain of the brand (owned or competitor) the row reports on",
            "example": "acme.com"
          },
          "visibility": {
            "type": "number",
            "description": "Visibility of the brand (0-1 scale)",
            "example": 0.25
          },
          "engine": {
            "type": "string",
            "enum": [
              "google-ai-overviews",
              "google-ai-mode",
              "perplexity",
              "openai",
              "gemini",
              "grok",
              "copilot",
              "claude"
            ],
            "description": "AI engine the row was observed on",
            "example": "openai"
          }
        },
        "required": [
          "brandId",
          "brandName",
          "brandDomain",
          "topicId",
          "topicName",
          "topicType",
          "topicLocation",
          "topicTags",
          "date",
          "rank",
          "relationship",
          "row",
          "brand",
          "domain",
          "visibility",
          "engine"
        ],
        "description": "Topic-level visibility export row"
      },
      "ExportTopicCitationsRow": {
        "type": "object",
        "properties": {
          "brandId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the brand the export was requested for",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "brandName": {
            "type": "string",
            "description": "Name of the brand the export was requested for",
            "example": "Acme Corporation"
          },
          "brandDomain": {
            "type": "string",
            "description": "Domain of the brand the export was requested for",
            "example": "acme.com"
          },
          "topicId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the topic the row belongs to",
            "example": "550e8400-e29b-41d4-a716-446655440001"
          },
          "topicName": {
            "type": "string",
            "description": "Name of the topic the row belongs to",
            "example": "project management software"
          },
          "topicType": {
            "type": "string",
            "nullable": true,
            "description": "Type of the topic (e.g. category) or `null` if not set"
          },
          "topicLocation": {
            "type": "string",
            "nullable": true,
            "description": "Location (country code) the topic is monitored for",
            "example": "us"
          },
          "topicTags": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Tags associated with the topic, or `null` if the topic has no tags",
            "example": [
              "product",
              "high-priority"
            ]
          },
          "date": {
            "type": "string",
            "description": "Day the row covers, formatted as `YYYY-MM-DD`",
            "example": "2026-01-01"
          },
          "rank": {
            "type": "number",
            "nullable": true,
            "description": "Ranking of the brand within the partition, or `null` when not applicable",
            "example": 3
          },
          "relationship": {
            "type": "string",
            "enum": [
              "owned",
              "competitor"
            ],
            "description": "Whether the row belongs to the owned brand (`owned`) or to a competing brand (`competitor`)"
          },
          "row": {
            "type": "integer",
            "description": "Stable ordering index across the whole response",
            "example": 1
          },
          "citedDomain": {
            "type": "string",
            "description": "Domain of the cited source",
            "example": "example.com"
          },
          "citedUrl": {
            "type": "string",
            "description": "URL of the cited source",
            "example": "https://example.com/reviews"
          },
          "citedTitle": {
            "type": "string",
            "nullable": true,
            "description": "Title of the cited source, if available",
            "example": "Best project management tools of 2026"
          },
          "totalCitations": {
            "type": "integer",
            "description": "Total number of citations the source received",
            "example": 7
          },
          "shareOfVoice": {
            "type": "number",
            "description": "Share of voice attributed to the cited source (0-1 scale)",
            "example": 0.25
          },
          "engine": {
            "type": "string",
            "enum": [
              "google-ai-overviews",
              "google-ai-mode",
              "perplexity",
              "openai",
              "gemini",
              "grok",
              "copilot",
              "claude"
            ],
            "description": "AI engine the row was observed on",
            "example": "openai"
          }
        },
        "required": [
          "brandId",
          "brandName",
          "brandDomain",
          "topicId",
          "topicName",
          "topicType",
          "topicLocation",
          "topicTags",
          "date",
          "rank",
          "relationship",
          "row",
          "citedDomain",
          "citedUrl",
          "totalCitations",
          "shareOfVoice",
          "engine"
        ],
        "description": "Topic-level citations export row"
      },
      "ExportPromptShareOfVoiceRow": {
        "type": "object",
        "properties": {
          "brandId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the brand the export was requested for",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "brandName": {
            "type": "string",
            "description": "Name of the brand the export was requested for",
            "example": "Acme Corporation"
          },
          "brandDomain": {
            "type": "string",
            "description": "Domain of the brand the export was requested for",
            "example": "acme.com"
          },
          "topicId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the topic the row belongs to",
            "example": "550e8400-e29b-41d4-a716-446655440001"
          },
          "topicName": {
            "type": "string",
            "description": "Name of the topic the row belongs to",
            "example": "project management software"
          },
          "topicType": {
            "type": "string",
            "nullable": true,
            "description": "Type of the topic (e.g. category) or `null` if not set"
          },
          "topicLocation": {
            "type": "string",
            "nullable": true,
            "description": "Location (country code) the topic is monitored for",
            "example": "us"
          },
          "topicTags": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Tags associated with the topic, or `null` if the topic has no tags",
            "example": [
              "product",
              "high-priority"
            ]
          },
          "promptId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the prompt the row belongs to",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "promptQuery": {
            "type": "string",
            "description": "The question sent to the AI engine for this prompt",
            "example": "What is the best project management tool for remote teams?"
          },
          "promptTags": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Tags associated with the prompt, or `null` if the prompt has no tags",
            "example": [
              "product",
              "high-priority"
            ]
          },
          "promptLocation": {
            "type": "string",
            "nullable": true,
            "description": "ISO 3166-1 alpha-2 country code for the prompt's target market",
            "example": "us"
          },
          "date": {
            "type": "string",
            "description": "Day the row covers, formatted as `YYYY-MM-DD`",
            "example": "2026-01-01"
          },
          "rank": {
            "type": "number",
            "nullable": true,
            "description": "Ranking of the brand within the partition, or `null` when not applicable",
            "example": 3
          },
          "relationship": {
            "type": "string",
            "enum": [
              "owned",
              "competitor"
            ],
            "description": "Whether the row belongs to the owned brand (`owned`) or to a competing brand (`competitor`)"
          },
          "row": {
            "type": "integer",
            "description": "Stable ordering index across the whole response",
            "example": 1
          },
          "brand": {
            "type": "string",
            "description": "Name of the brand (owned or competitor) the row reports on",
            "example": "Acme Corporation"
          },
          "domain": {
            "type": "string",
            "description": "Domain of the brand (owned or competitor) the row reports on",
            "example": "acme.com"
          },
          "mentionCount": {
            "type": "integer",
            "description": "Number of times the brand was mentioned",
            "example": 12
          },
          "shareOfVoice": {
            "type": "number",
            "description": "Share of voice of the brand (0-1 scale)",
            "example": 0.25
          },
          "engine": {
            "type": "string",
            "enum": [
              "google-ai-overviews",
              "google-ai-mode",
              "perplexity",
              "openai",
              "gemini",
              "grok",
              "copilot",
              "claude"
            ],
            "description": "AI engine the row was observed on",
            "example": "openai"
          }
        },
        "required": [
          "brandId",
          "brandName",
          "brandDomain",
          "topicId",
          "topicName",
          "topicType",
          "topicLocation",
          "topicTags",
          "promptId",
          "promptQuery",
          "promptTags",
          "promptLocation",
          "date",
          "rank",
          "relationship",
          "row",
          "brand",
          "domain",
          "mentionCount",
          "shareOfVoice",
          "engine"
        ],
        "description": "Prompt-level share of voice export row"
      },
      "ExportPromptVisibilityRow": {
        "type": "object",
        "properties": {
          "brandId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the brand the export was requested for",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "brandName": {
            "type": "string",
            "description": "Name of the brand the export was requested for",
            "example": "Acme Corporation"
          },
          "brandDomain": {
            "type": "string",
            "description": "Domain of the brand the export was requested for",
            "example": "acme.com"
          },
          "topicId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the topic the row belongs to",
            "example": "550e8400-e29b-41d4-a716-446655440001"
          },
          "topicName": {
            "type": "string",
            "description": "Name of the topic the row belongs to",
            "example": "project management software"
          },
          "topicType": {
            "type": "string",
            "nullable": true,
            "description": "Type of the topic (e.g. category) or `null` if not set"
          },
          "topicLocation": {
            "type": "string",
            "nullable": true,
            "description": "Location (country code) the topic is monitored for",
            "example": "us"
          },
          "topicTags": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Tags associated with the topic, or `null` if the topic has no tags",
            "example": [
              "product",
              "high-priority"
            ]
          },
          "promptId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the prompt the row belongs to",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "promptQuery": {
            "type": "string",
            "description": "The question sent to the AI engine for this prompt",
            "example": "What is the best project management tool for remote teams?"
          },
          "promptTags": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Tags associated with the prompt, or `null` if the prompt has no tags",
            "example": [
              "product",
              "high-priority"
            ]
          },
          "promptLocation": {
            "type": "string",
            "nullable": true,
            "description": "ISO 3166-1 alpha-2 country code for the prompt's target market",
            "example": "us"
          },
          "date": {
            "type": "string",
            "description": "Day the row covers, formatted as `YYYY-MM-DD`",
            "example": "2026-01-01"
          },
          "rank": {
            "type": "number",
            "nullable": true,
            "description": "Ranking of the brand within the partition, or `null` when not applicable",
            "example": 3
          },
          "relationship": {
            "type": "string",
            "enum": [
              "owned",
              "competitor"
            ],
            "description": "Whether the row belongs to the owned brand (`owned`) or to a competing brand (`competitor`)"
          },
          "row": {
            "type": "integer",
            "description": "Stable ordering index across the whole response",
            "example": 1
          },
          "brand": {
            "type": "string",
            "description": "Name of the brand (owned or competitor) the row reports on",
            "example": "Acme Corporation"
          },
          "domain": {
            "type": "string",
            "description": "Domain of the brand (owned or competitor) the row reports on",
            "example": "acme.com"
          },
          "visibility": {
            "type": "number",
            "description": "Visibility of the brand (0-1 scale)",
            "example": 0.25
          },
          "engine": {
            "type": "string",
            "enum": [
              "google-ai-overviews",
              "google-ai-mode",
              "perplexity",
              "openai",
              "gemini",
              "grok",
              "copilot",
              "claude"
            ],
            "description": "AI engine the row was observed on",
            "example": "openai"
          }
        },
        "required": [
          "brandId",
          "brandName",
          "brandDomain",
          "topicId",
          "topicName",
          "topicType",
          "topicLocation",
          "topicTags",
          "promptId",
          "promptQuery",
          "promptTags",
          "promptLocation",
          "date",
          "rank",
          "relationship",
          "row",
          "brand",
          "domain",
          "visibility",
          "engine"
        ],
        "description": "Prompt-level visibility export row"
      },
      "ExportPromptCitationsRow": {
        "type": "object",
        "properties": {
          "brandId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the brand the export was requested for",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "brandName": {
            "type": "string",
            "description": "Name of the brand the export was requested for",
            "example": "Acme Corporation"
          },
          "brandDomain": {
            "type": "string",
            "description": "Domain of the brand the export was requested for",
            "example": "acme.com"
          },
          "topicId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the topic the row belongs to",
            "example": "550e8400-e29b-41d4-a716-446655440001"
          },
          "topicName": {
            "type": "string",
            "description": "Name of the topic the row belongs to",
            "example": "project management software"
          },
          "topicType": {
            "type": "string",
            "nullable": true,
            "description": "Type of the topic (e.g. category) or `null` if not set"
          },
          "topicLocation": {
            "type": "string",
            "nullable": true,
            "description": "Location (country code) the topic is monitored for",
            "example": "us"
          },
          "topicTags": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Tags associated with the topic, or `null` if the topic has no tags",
            "example": [
              "product",
              "high-priority"
            ]
          },
          "promptId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the prompt the row belongs to",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "promptQuery": {
            "type": "string",
            "description": "The question sent to the AI engine for this prompt",
            "example": "What is the best project management tool for remote teams?"
          },
          "promptTags": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Tags associated with the prompt, or `null` if the prompt has no tags",
            "example": [
              "product",
              "high-priority"
            ]
          },
          "promptLocation": {
            "type": "string",
            "nullable": true,
            "description": "ISO 3166-1 alpha-2 country code for the prompt's target market",
            "example": "us"
          },
          "date": {
            "type": "string",
            "description": "Day the row covers, formatted as `YYYY-MM-DD`",
            "example": "2026-01-01"
          },
          "rank": {
            "type": "number",
            "nullable": true,
            "description": "Ranking of the brand within the partition, or `null` when not applicable",
            "example": 3
          },
          "relationship": {
            "type": "string",
            "enum": [
              "owned",
              "competitor"
            ],
            "description": "Whether the row belongs to the owned brand (`owned`) or to a competing brand (`competitor`)"
          },
          "row": {
            "type": "integer",
            "description": "Stable ordering index across the whole response",
            "example": 1
          },
          "citedDomain": {
            "type": "string",
            "description": "Domain of the cited source",
            "example": "example.com"
          },
          "citedUrl": {
            "type": "string",
            "description": "URL of the cited source",
            "example": "https://example.com/reviews"
          },
          "citedTitle": {
            "type": "string",
            "nullable": true,
            "description": "Title of the cited source, if available",
            "example": "Best project management tools of 2026"
          },
          "totalCitations": {
            "type": "integer",
            "description": "Total number of citations the source received",
            "example": 7
          },
          "shareOfVoice": {
            "type": "number",
            "description": "Share of voice attributed to the cited source (0-1 scale)",
            "example": 0.25
          },
          "engine": {
            "type": "string",
            "enum": [
              "google-ai-overviews",
              "google-ai-mode",
              "perplexity",
              "openai",
              "gemini",
              "grok",
              "copilot",
              "claude"
            ],
            "description": "AI engine the row was observed on",
            "example": "openai"
          }
        },
        "required": [
          "brandId",
          "brandName",
          "brandDomain",
          "topicId",
          "topicName",
          "topicType",
          "topicLocation",
          "topicTags",
          "promptId",
          "promptQuery",
          "promptTags",
          "promptLocation",
          "date",
          "rank",
          "relationship",
          "row",
          "citedDomain",
          "citedUrl",
          "totalCitations",
          "shareOfVoice",
          "engine"
        ],
        "description": "Prompt-level citations export row"
      },
      "ExportRow": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/ExportBrandShareOfVoiceRow"
          },
          {
            "$ref": "#/components/schemas/ExportBrandVisibilityRow"
          },
          {
            "$ref": "#/components/schemas/ExportBrandCitationsRow"
          },
          {
            "$ref": "#/components/schemas/ExportTopicShareOfVoiceRow"
          },
          {
            "$ref": "#/components/schemas/ExportTopicVisibilityRow"
          },
          {
            "$ref": "#/components/schemas/ExportTopicCitationsRow"
          },
          {
            "$ref": "#/components/schemas/ExportPromptShareOfVoiceRow"
          },
          {
            "$ref": "#/components/schemas/ExportPromptVisibilityRow"
          },
          {
            "$ref": "#/components/schemas/ExportPromptCitationsRow"
          }
        ],
        "description": "A single row of an analytics export. The full response body is a sequence of these objects separated by newlines (NDJSON)."
      },
      "LongRunningTaskCreationLinks": {
        "type": "object",
        "properties": {
          "self": {
            "type": "string",
            "format": "uri",
            "description": "URL to request the status of this task",
            "example": "https://app.useomnia.com/api/v1/resource"
          }
        },
        "required": [
          "self"
        ],
        "description": "Navigation links for long-running task creation responses"
      },
      "CreateExportResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "Unique identifier for the metrics export"
              },
              "type": {
                "type": "string",
                "enum": [
                  "metrics_export"
                ],
                "description": "The type of export"
              },
              "links": {
                "$ref": "#/components/schemas/LongRunningTaskCreationLinks"
              }
            },
            "required": [
              "id",
              "type",
              "links"
            ]
          }
        },
        "required": [
          "data"
        ],
        "description": "Response after successfully created a metrics export task"
      },
      "CreateBrandPromptsSummary": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of prompts submitted"
          },
          "created": {
            "type": "integer",
            "description": "Number of prompts successfully created"
          },
          "skipped": {
            "type": "integer",
            "description": "Number of prompts skipped because they already exist"
          },
          "errors": {
            "type": "integer",
            "description": "Number of prompts that failed due to validation or processing errors"
          }
        },
        "required": [
          "total",
          "created",
          "skipped",
          "errors"
        ]
      },
      "CreateBrandPromptsErrorItem": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer",
            "description": "1-based index of the prompt in the request array that failed"
          },
          "prompt": {
            "type": "string",
            "description": "The prompt text that failed",
            "example": "What is the best CRM for small businesses?"
          },
          "reason": {
            "type": "string",
            "description": "Human-readable explanation of why the prompt failed",
            "example": "Country code 'xx' is not a valid ISO 3166-1 alpha-2 code"
          }
        },
        "required": [
          "index",
          "prompt",
          "reason"
        ]
      },
      "CreateBrandPromptsSkippedItem": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer",
            "description": "1-based index of the prompt in the request array that was skipped"
          },
          "prompt": {
            "type": "string",
            "description": "The prompt text that was skipped",
            "example": "What is the best CRM for small businesses?"
          }
        },
        "required": [
          "index",
          "prompt"
        ]
      },
      "CreateBrandPromptsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "summary": {
                "$ref": "#/components/schemas/CreateBrandPromptsSummary"
              },
              "errors": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CreateBrandPromptsErrorItem"
                },
                "description": "Prompts that failed to be created"
              },
              "skipped": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CreateBrandPromptsSkippedItem"
                },
                "description": "Prompts skipped because they already exist"
              }
            },
            "required": [
              "summary",
              "errors",
              "skipped"
            ]
          }
        },
        "required": [
          "data"
        ],
        "description": "Report summarizing the outcome of a bulk prompt creation request"
      },
      "BrandPromptItem": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "description": "The exact question or statement to be sent to AI engines for monitoring",
            "example": "What is the best CRM for small businesses?"
          },
          "location": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code for the prompt's target market",
            "minLength": 2,
            "maxLength": 2,
            "pattern": "^[a-z]{2}$",
            "example": "us"
          },
          "topic": {
            "type": "string",
            "minLength": 1,
            "description": "Name of the topic to group this prompt under. If omitted, the prompt is placed in an auto-managed topic for the given location.",
            "example": "CRM Comparisons"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "User-defined labels for organizing and filtering this prompt",
            "example": [
              "product",
              "high-priority"
            ]
          }
        },
        "required": [
          "query",
          "location"
        ],
        "additionalProperties": false,
        "description": "A single prompt to create under a brand"
      },
      "CreateBrandPromptsBody": {
        "type": "object",
        "properties": {
          "prompts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BrandPromptItem"
            },
            "minItems": 1,
            "maxItems": 2000,
            "description": "Array of prompts to create. Maximum 2000 prompts per request."
          },
          "source": {
            "type": "string",
            "enum": [
              "add_brand",
              "omnio:onboarding:setup",
              "omnio:generate-prompts",
              "add_topic",
              "prompt_discovery_keywords",
              "prompt_discovery_topics",
              "add_prompt",
              "topic_explorer",
              "mcp_trends",
              "new_topics",
              "csv_import",
              "public_api",
              "mcp",
              "aeo_report"
            ],
            "description": "Identifies what triggered this creation, for internal analytics attribution. Defaults to the calling client type when omitted.",
            "example": "public_api"
          }
        },
        "required": [
          "prompts"
        ],
        "additionalProperties": false,
        "description": "Request body for bulk-creating prompts for a brand"
      },
      "BrandPromptListItem": {
        "type": "object",
        "properties": {
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp indicating when the prompt was created",
            "example": "2026-01-01T09:30:00Z"
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the prompt",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "isMonitoringActive": {
            "type": "boolean",
            "description": "Whether AI responses are being tracked for this prompt",
            "example": true
          },
          "location": {
            "type": "string",
            "nullable": true,
            "description": "ISO 3166-1 alpha-2 country code for the prompt's target market",
            "example": "us"
          },
          "query": {
            "type": "string",
            "description": "The exact text sent to AI engines when monitoring this prompt",
            "example": "What is the best CRM for small businesses?"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "User-defined labels for organizing and filtering prompts",
            "example": [
              "product",
              "high-priority"
            ]
          },
          "type": {
            "type": "string",
            "nullable": true,
            "enum": [
              "Branded",
              "Non-Branded"
            ],
            "description": "Whether the prompt contains your brand name (`Branded`) or is a generic query (`Non-Branded`)",
            "example": "Non-Branded"
          },
          "shareOfVoice": {
            "type": "number",
            "description": "Aggregate share of voice score (0-1) for the owned brand across all AI engines in the requested date range",
            "example": 0.25
          },
          "netSentiment": {
            "type": "number",
            "description": "Net sentiment score (-1 to 1) for the owned brand in the requested date range, based on the balance of endorsed vs undermined feature mentions. Positive values indicate favorable sentiment, negative values indicate unfavorable sentiment",
            "example": 0.42
          }
        },
        "required": [
          "createdAt",
          "id",
          "isMonitoringActive",
          "query",
          "tags",
          "type",
          "shareOfVoice",
          "netSentiment"
        ],
        "description": "A prompt with summary performance metrics, returned in brand-level list responses"
      },
      "BrandPromptsListResponseData": {
        "type": "object",
        "properties": {
          "prompts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BrandPromptListItem"
            },
            "description": "Array of prompt objects belonging to the specified brand"
          }
        },
        "required": [
          "prompts"
        ]
      },
      "BrandPromptsListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaginatedResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/BrandPromptsListResponseData"
              }
            },
            "required": [
              "data"
            ]
          }
        ],
        "description": "Paginated response containing the list of prompts for a brand"
      },
      "MetricsExport": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the export",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "status": {
            "type": "string",
            "enum": [
              "progress",
              "completed",
              "failed"
            ],
            "description": "Status of the metrics export"
          },
          "error": {
            "type": "string",
            "description": "Error description of the export if failed"
          },
          "resultsUrl": {
            "type": "string",
            "format": "uri",
            "description": "A presigned URL to download the export results in CSV format. This URL expires 7 days after generation."
          }
        },
        "required": [
          "id",
          "status"
        ],
        "description": "A metrics export task"
      },
      "MetricsExportResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/MetricsExport"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing a metrics export"
      },
      "InsightPosition": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "enum": [
              "missing",
              "lagging",
              "competing",
              "leading",
              "top_one"
            ],
            "description": "Brand's competitive position for this prompt",
            "example": "missing"
          },
          "brandSov": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Brand's share of voice for this prompt (0–1)",
            "example": 0.12
          },
          "competitorCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of competitors mentioned in the AI response",
            "example": 5
          }
        },
        "required": [
          "label",
          "brandSov",
          "competitorCount"
        ],
        "description": "Brand's competitive position relative to competitors"
      },
      "InsightHypothesis": {
        "type": "object",
        "properties": {
          "claim": {
            "type": "string",
            "description": "The core hypothesis the insight is based on",
            "example": "Creating a definitive guide on this topic will improve brand visibility"
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Key assumptions underlying the hypothesis"
          },
          "confidence": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ],
            "description": "Confidence level in the hypothesis",
            "example": "low"
          },
          "confidenceRationale": {
            "type": "string",
            "description": "Explanation of why this confidence level was assigned"
          }
        },
        "required": [
          "claim",
          "assumptions",
          "confidence",
          "confidenceRationale"
        ]
      },
      "InsightSummary": {
        "type": "object",
        "properties": {
          "headline": {
            "type": "string",
            "description": "Short title summarizing the insight",
            "example": "Create a definitive guide on AI-powered analytics"
          },
          "rationale": {
            "type": "string",
            "description": "Why this insight matters for the brand"
          },
          "expectedOutcome": {
            "type": "string",
            "description": "What result implementing this insight should produce"
          }
        },
        "required": [
          "headline",
          "rationale",
          "expectedOutcome"
        ]
      },
      "InsightRecommendation": {
        "type": "object",
        "properties": {
          "tactic": {
            "type": "string",
            "enum": [
              "create_and_place",
              "create_owned",
              "update_existing"
            ],
            "description": "Recommended content tactic",
            "example": "create_and_place"
          },
          "contentType": {
            "type": "string",
            "enum": [
              "definitive_guide",
              "comparison",
              "listicle",
              "how_to",
              "case_study",
              "expert_opinion",
              "data_research",
              "directory_listing",
              "community_contribution",
              "glossary_definition"
            ],
            "description": "Suggested content format",
            "example": "definitive_guide"
          },
          "targetChannel": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "owned",
                  "editorial",
                  "directory",
                  "community",
                  "developer",
                  "social"
                ],
                "description": "Channel category for content placement",
                "example": "owned"
              },
              "domain": {
                "type": "string",
                "description": "Specific domain or platform to target",
                "example": "blog.acme.com"
              }
            },
            "required": [
              "type",
              "domain"
            ],
            "description": "Where to publish or place the content"
          },
          "brief": {
            "type": "string",
            "description": "Actionable content brief describing what to create"
          }
        },
        "required": [
          "tactic",
          "contentType",
          "targetChannel",
          "brief"
        ]
      },
      "ActionInsightData": {
        "type": "object",
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "positioning",
              "sentiment"
            ],
            "description": "Analytical lens used for this insight",
            "example": "positioning"
          },
          "position": {
            "$ref": "#/components/schemas/InsightPosition"
          },
          "hypothesis": {
            "$ref": "#/components/schemas/InsightHypothesis"
          },
          "summary": {
            "$ref": "#/components/schemas/InsightSummary"
          },
          "recommendation": {
            "$ref": "#/components/schemas/InsightRecommendation"
          }
        },
        "required": [
          "category",
          "position",
          "hypothesis",
          "summary",
          "recommendation"
        ],
        "description": "Data for action insights. Contains a recommendation to improve brand visibility"
      },
      "SuggestedPrompt": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Suggested search query to monitor",
            "example": "best analytics tools for startups"
          },
          "rationale": {
            "type": "string",
            "description": "Why this query is worth monitoring"
          }
        },
        "required": [
          "query",
          "rationale"
        ]
      },
      "MonitorInsightData": {
        "type": "object",
        "properties": {
          "summary": {
            "$ref": "#/components/schemas/InsightSummary"
          },
          "decision": {
            "type": "string",
            "enum": [
              "monitor_only",
              "redirect_to_adjacent"
            ],
            "description": "Whether to just monitor or redirect effort to an adjacent prompt",
            "example": "monitor_only"
          },
          "confidence": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ],
            "description": "Confidence level in the monitoring decision",
            "example": "low"
          },
          "confidenceRationale": {
            "type": "string",
            "description": "Explanation of why this confidence level was assigned"
          },
          "suggestedPrompts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SuggestedPrompt"
            },
            "description": "Additional prompts suggested for monitoring"
          },
          "monitoredQueries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Queries already being monitored for this insight"
          }
        },
        "required": [
          "summary",
          "decision",
          "confidence",
          "confidenceRationale"
        ],
        "description": "Data for monitor insights. Suggests keeping an eye on a prompt without immediate action"
      },
      "Insight": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the insight",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "type": {
            "type": "string",
            "enum": [
              "action",
              "monitor"
            ],
            "description": "Whether this insight recommends an action or suggests monitoring",
            "example": "action"
          },
          "engine": {
            "type": "string",
            "description": "AI engine that was queried when this insight was generated",
            "example": "chatgpt"
          },
          "data": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ActionInsightData"
              },
              {
                "$ref": "#/components/schemas/MonitorInsightData"
              }
            ],
            "description": "Type-specific insight payload (action or monitor)"
          },
          "impact": {
            "type": "string",
            "nullable": true,
            "enum": [
              "low",
              "medium",
              "high"
            ],
            "description": "Estimated impact level of acting on this insight",
            "example": "low"
          },
          "title": {
            "type": "string",
            "description": "Short headline summarizing the insight",
            "example": "Create a definitive guide on AI-powered analytics"
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "completed",
              "dismissed"
            ],
            "description": "Current workflow status of the insight",
            "example": "open"
          },
          "statusChangedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time",
            "description": "ISO 8601 timestamp of the last status change",
            "example": "2026-01-01T09:30:00Z"
          },
          "dismissedFeedback": {
            "type": "string",
            "nullable": true,
            "description": "User-provided reason for dismissing the insight"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp when the insight was created",
            "example": "2026-01-01T09:30:00Z"
          }
        },
        "required": [
          "id",
          "type",
          "engine",
          "data",
          "impact",
          "title",
          "status",
          "statusChangedAt",
          "dismissedFeedback",
          "createdAt"
        ],
        "description": "A brand insight generated from AI engine analysis"
      },
      "InsightsListResponseData": {
        "type": "object",
        "properties": {
          "insights": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Insight"
            },
            "description": "Array of insights for the brand"
          }
        },
        "required": [
          "insights"
        ]
      },
      "InsightsListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaginatedResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/InsightsListResponseData"
              }
            },
            "required": [
              "data"
            ]
          }
        ],
        "description": "Paginated response containing the list of insights"
      },
      "InsightResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Insight"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing a single insight"
      },
      "PatchInsightBodyCompleted": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "completed"
            ],
            "description": "Mark the insight as completed"
          },
          "completedUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL of the content created as a result of completing this insight",
            "example": "https://example.com/blog/my-post"
          }
        },
        "required": [
          "status"
        ]
      },
      "PatchInsightBodyDismissed": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "dismissed"
            ],
            "description": "Dismiss the insight without acting on it"
          },
          "dismissedFeedback": {
            "type": "string",
            "maxLength": 250,
            "description": "Optional reason for dismissing the insight (max 250 characters)",
            "example": "Not relevant for our current strategy"
          }
        },
        "required": [
          "status"
        ]
      },
      "PatchInsightBodyOpen": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "open"
            ],
            "description": "Reopen a previously completed or dismissed insight"
          }
        },
        "required": [
          "status"
        ]
      },
      "PatchInsightBody": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/PatchInsightBodyCompleted"
          },
          {
            "$ref": "#/components/schemas/PatchInsightBodyDismissed"
          },
          {
            "$ref": "#/components/schemas/PatchInsightBodyOpen"
          }
        ],
        "discriminator": {
          "propertyName": "status",
          "mapping": {
            "completed": "#/components/schemas/PatchInsightBodyCompleted",
            "dismissed": "#/components/schemas/PatchInsightBodyDismissed",
            "open": "#/components/schemas/PatchInsightBodyOpen"
          }
        },
        "description": "Request body for updating an insight's status"
      },
      "CreateInsightResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Unique identifier for the insight generation"
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "insights_generation"
                  ],
                  "description": "The type of generation"
                },
                "engine": {
                  "type": "string",
                  "enum": [
                    "google-ai-overviews",
                    "google-ai-mode",
                    "perplexity",
                    "openai",
                    "gemini",
                    "grok",
                    "copilot",
                    "claude"
                  ],
                  "description": "The engine used for this generation"
                },
                "links": {
                  "$ref": "#/components/schemas/LongRunningTaskCreationLinks"
                }
              },
              "required": [
                "id",
                "type",
                "engine",
                "links"
              ]
            }
          }
        },
        "required": [
          "data"
        ],
        "description": "Response after successfully created a new insight generation"
      },
      "CreateInsightBody": {
        "type": "object",
        "properties": {
          "engines": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ]
            },
            "minItems": 1,
            "description": "AI engines to analyze for brand visibility insights",
            "example": [
              "openai",
              "perplexity"
            ]
          },
          "question": {
            "type": "string",
            "description": "Additional context or specific question to guide the analysis",
            "example": "Why is our brand not appearing in comparison queries?"
          }
        },
        "required": [
          "engines"
        ],
        "description": "Request body for creating a new insight"
      },
      "InsightGeneration": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the generation",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "brandId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the parent brand",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "promptId": {
            "type": "string",
            "nullable": true,
            "format": "uuid",
            "description": "Unique identifier for the analyzed prompt (null when the generation targets a non-prompt entity)",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "engine": {
            "type": "string",
            "description": "AI engine used to analyze for brand visibility insights",
            "example": "openai"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "running",
              "completed",
              "failed",
              "cancelled"
            ],
            "description": "Status of the insights generation"
          },
          "error": {
            "type": "string",
            "nullable": true,
            "description": "Error description of the generation if failed"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp indicating when the insights generation was created",
            "example": "2026-01-01T09:30:00Z"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Insight"
            },
            "description": "A list of generated insights. This field is only present if generation status is completed"
          }
        },
        "required": [
          "id",
          "brandId",
          "promptId",
          "engine",
          "status",
          "error",
          "createdAt"
        ],
        "description": "An insight generation task"
      },
      "InsightGenerationResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/InsightGeneration"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing a single insight generation"
      },
      "ProjectListItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the Project",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "reference": {
            "type": "string",
            "description": "Short human-readable reference, unique within the brand",
            "example": "PRJ-42"
          },
          "headline": {
            "type": "string",
            "description": "One-line title of the work",
            "example": "Win the comparison prompts competitors own"
          },
          "summary": {
            "type": "string",
            "description": "Short description of the work and why it matters",
            "example": "Competitors are cited in every comparison prompt; a comparison page would close it."
          },
          "status": {
            "type": "string",
            "enum": [
              "suggested",
              "to_do",
              "in_progress",
              "done"
            ],
            "description": "The Project's status. `suggested` is a proposal not yet accepted; `to_do`, `in_progress` and `done` are accepted work",
            "example": "in_progress"
          },
          "category": {
            "type": "string",
            "nullable": true,
            "enum": [
              "content_creation",
              "content_optimization",
              "technical",
              "outreach",
              "monitoring"
            ],
            "description": "The kind of work the Project is, or null when none was set",
            "example": "technical"
          },
          "createdBy": {
            "type": "string",
            "enum": [
              "user",
              "omnio"
            ],
            "description": "`omnio` for a Project Omnia Agent suggested, `user` for one the user created",
            "example": "omnio"
          },
          "conversationId": {
            "type": "string",
            "format": "uuid",
            "description": "Identifier of the Omnia Agent conversation the work happens in",
            "example": "550e8400-e29b-41d4-a716-446655440001"
          },
          "awaitingUserSince": {
            "type": "string",
            "nullable": true,
            "format": "date-time",
            "description": "ISO 8601 timestamp since when Omnia Agent waits on the user in the Project's conversation, or null when it does not",
            "example": null
          },
          "hasActiveTurn": {
            "type": "boolean",
            "description": "Whether Omnia Agent is working on the Project right now",
            "example": false
          },
          "acceptedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time",
            "description": "ISO 8601 timestamp when the Project became accepted work, by accepting its suggestion or by being created as accepted work, or null while it is still a suggestion",
            "example": "2026-01-01T09:30:00Z"
          },
          "discardedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time",
            "description": "ISO 8601 timestamp when the Project was discarded, or null when it was not",
            "example": null
          },
          "discardReason": {
            "type": "string",
            "nullable": true,
            "enum": [
              "not_relevant",
              "low_priority",
              "already_done",
              "not_aligned",
              "other"
            ],
            "description": "Why the Project was discarded, or null when it was not or was discarded without a reason",
            "example": null
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp when the Project was created",
            "example": "2026-01-01T09:30:00Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp when the Project last changed",
            "example": "2026-01-01T09:30:00Z"
          }
        },
        "required": [
          "id",
          "reference",
          "headline",
          "summary",
          "status",
          "category",
          "createdBy",
          "conversationId",
          "awaitingUserSince",
          "hasActiveTurn",
          "acceptedAt",
          "discardedAt",
          "discardReason",
          "createdAt",
          "updatedAt"
        ],
        "description": "A Project as the board lists it"
      },
      "BrandProjectsListResponseData": {
        "type": "object",
        "properties": {
          "projects": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProjectListItem"
            },
            "description": "The Projects on this page"
          }
        },
        "required": [
          "projects"
        ]
      },
      "BrandProjectsListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaginatedResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/BrandProjectsListResponseData"
              }
            },
            "required": [
              "data"
            ]
          }
        ],
        "description": "Paginated response containing a brand's Projects"
      },
      "Project": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ProjectListItem"
          },
          {
            "type": "object",
            "properties": {
              "body": {
                "type": "string",
                "description": "Full Markdown description of the work",
                "example": "## Diagnosis\nCompetitors are cited in every comparison prompt."
              },
              "outcomeSummary": {
                "type": "string",
                "nullable": true,
                "description": "What the finished work achieved, as the user wrote it, or null",
                "example": null
              },
              "discardExplanation": {
                "type": "string",
                "nullable": true,
                "description": "Free-text explanation that came with the discard, or null",
                "example": null
              }
            },
            "required": [
              "body",
              "outcomeSummary",
              "discardExplanation"
            ]
          }
        ],
        "description": "A Project with its full description"
      },
      "ProjectResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Project"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing a single Project"
      },
      "CreateProjectBody": {
        "type": "object",
        "properties": {
          "headline": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "The Project's name, up to 80 characters",
            "example": "Publish a comparison page against the main competitor"
          },
          "summary": {
            "type": "string",
            "minLength": 1,
            "maxLength": 280,
            "description": "One or two plain-text sentences saying what the work is, up to 280 characters",
            "example": "Competitors are cited in every comparison prompt; a comparison page would close it."
          },
          "body": {
            "type": "string",
            "minLength": 1,
            "maxLength": 8000,
            "description": "The full description in Markdown, up to 8000 characters: why the work matters, what to do and the expected result.",
            "example": "## Why now\nCompetitors are cited in every comparison prompt."
          },
          "status": {
            "type": "string",
            "enum": [
              "to_do",
              "in_progress"
            ],
            "default": "to_do",
            "description": "Status the Project starts in",
            "example": "to_do"
          },
          "category": {
            "type": "string",
            "nullable": true,
            "enum": [
              "content_creation",
              "content_optimization",
              "technical",
              "outreach",
              "monitoring"
            ],
            "default": null,
            "description": "The kind of work the Project is. Optional, but set it whenever one fits: content_creation (publish a page or asset that does not exist yet), content_optimization (change a page or asset the brand already has), technical (how engines crawl, render and read the site, such as robots.txt, sitemaps or schema), outreach (sources the brand does not own) or monitoring (what Omnia measures for the brand).",
            "example": null
          }
        },
        "required": [
          "headline",
          "summary",
          "body"
        ],
        "additionalProperties": false,
        "description": "The content of a new Project"
      },
      "ProjectFile": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Identifier of this version of the file. It keeps naming the same version after newer ones are saved.",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "filename": {
            "type": "string",
            "description": "The file's name",
            "example": "comparison-page.md"
          },
          "contentType": {
            "type": "string",
            "description": "MIME type of the file",
            "example": "text/markdown"
          },
          "sizeBytes": {
            "type": "integer",
            "description": "Size of the file in bytes",
            "example": 4096
          },
          "version": {
            "type": "integer",
            "description": "Version number of the file; the list returns only the latest one",
            "example": 2
          },
          "createdBy": {
            "type": "string",
            "enum": [
              "user",
              "omnio"
            ],
            "description": "`omnio` for a file Omnia Agent created, `user` for one the user uploaded",
            "example": "omnio"
          },
          "storedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time",
            "description": "ISO 8601 timestamp when this version was saved",
            "example": "2026-01-01T09:30:00Z"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Signed URL that downloads the file's content until `urlsExpireAt`",
            "example": "https://files.example.com/comparison-page.md?signature=abc"
          }
        },
        "required": [
          "id",
          "filename",
          "contentType",
          "sizeBytes",
          "version",
          "createdBy",
          "storedAt",
          "url"
        ],
        "description": "A file in a Project, with a URL to download it"
      },
      "ProjectFilesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "files": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ProjectFile"
                }
              },
              "urlsExpireAt": {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp when every `url` stops working; list the files again for new ones",
                "example": "2026-01-01T09:30:00Z"
              }
            },
            "required": [
              "files",
              "urlsExpireAt"
            ]
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing a Project's files"
      },
      "PatchProjectBody": {
        "type": "object",
        "properties": {
          "headline": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "The Project's one-line title, up to 80 characters.",
            "example": "Win the comparison prompts competitors own"
          },
          "summary": {
            "type": "string",
            "minLength": 1,
            "maxLength": 280,
            "description": "What the work is, in one or two plain-text sentences, up to 280 characters. No Markdown.",
            "example": "Competitors are cited in every comparison prompt; a comparison page would close it."
          },
          "body": {
            "type": "string",
            "minLength": 1,
            "maxLength": 8000,
            "description": "The Project's brief in Markdown, up to 8000 characters: why now, the concrete work, and the expected result. Send the whole rewritten brief, never a diff.",
            "example": "## Diagnosis\nCompetitors are cited in every comparison prompt."
          },
          "category": {
            "type": "string",
            "nullable": true,
            "enum": [
              "content_creation",
              "content_optimization",
              "technical",
              "outreach",
              "monitoring"
            ],
            "description": "The kind of work the Project is, or `null` to clear it.",
            "example": "technical"
          },
          "status": {
            "type": "string",
            "enum": [
              "to_do",
              "in_progress",
              "done"
            ],
            "description": "Status to set. Accepting a suggestion sets `to_do` or `in_progress`; `done` closes the Project. A discarded Project moves only when the same call restores it with `discarded: false`.",
            "example": "in_progress"
          },
          "outcomeSummary": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "description": "What the finished work achieved, up to 500 characters. Accepted only together with `status: \"done\"`.",
            "example": "Published the comparison page; it is cited in two of the five tracked Prompts."
          },
          "discarded": {
            "type": "boolean",
            "description": "`true` discards the Project, with an optional `discardReason`; `false` restores a discarded Project with the status it had. `true` cannot be combined with `status`; `false` can, to restore the Project and move it in one call. A done Project cannot be discarded and is meant to stay done, not be reopened to discard it.",
            "example": true
          },
          "discardReason": {
            "type": "string",
            "enum": [
              "not_relevant",
              "low_priority",
              "already_done",
              "not_aligned",
              "other"
            ],
            "description": "Why the Project is discarded, accepted only together with `discarded: true`; omit it when the user gave no reason: not_relevant (the work does not apply or is not wanted), low_priority, already_done (the work already exists), not_aligned (it does not fit the brand's goals) or other.",
            "example": "already_done"
          },
          "discardExplanation": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "description": "Free-text explanation of the discard, up to 500 characters. Accepted only together with a `discardReason`, and required when it is `other`.",
            "example": "The comparison page already exists at /compare."
          }
        },
        "additionalProperties": false,
        "description": "Every field sent is applied together, in one change: a move (`status`, plus `outcomeSummary` when moving to `done`), a discard (`discarded: true`, plus a reason when the user gave one), a restore (`discarded: false`), a content rewrite (any of `headline`, `summary` and `body`) and a Category change (`category`). If any part is refused, nothing is changed. Fields combine freely, except `discarded: true` with `status`. A discarded Project keeps its content and Category editable, but must be restored before it moves. Fields left out stay as they are, and a call that changes nothing returns the Project unchanged."
      },
      "Prompt": {
        "type": "object",
        "properties": {
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp indicating when the prompt was created",
            "example": "2026-01-01T09:30:00Z"
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the prompt",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "isMonitoringActive": {
            "type": "boolean",
            "description": "Whether AI responses are being tracked for this prompt",
            "example": true
          },
          "location": {
            "type": "string",
            "nullable": true,
            "description": "ISO 3166-1 alpha-2 country code for the prompt's target market",
            "example": "us"
          },
          "query": {
            "type": "string",
            "description": "The exact text sent to AI engines when monitoring this prompt",
            "example": "What is the best software for small businesses?"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "User-defined labels for organizing and filtering prompts",
            "example": [
              "product",
              "high-priority"
            ]
          },
          "topicId": {
            "type": "string",
            "format": "uuid",
            "description": "Identifier of the parent topic this prompt belongs to",
            "example": "550e8400-e29b-41d4-a716-446655440001"
          },
          "type": {
            "type": "string",
            "nullable": true,
            "enum": [
              "Branded",
              "Non-Branded"
            ],
            "description": "Whether the prompt contains your brand name (`Branded`) or is a generic query (`Non-Branded`)",
            "example": "Non-Branded"
          }
        },
        "required": [
          "createdAt",
          "id",
          "isMonitoringActive",
          "query",
          "tags",
          "type"
        ],
        "description": "A prompt"
      },
      "PromptListItem": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Prompt"
          },
          {
            "type": "object",
            "properties": {
              "shareOfVoice": {
                "type": "number",
                "description": "Aggregate share of voice score (0-1) for the owned brand across all AI engines in the requested date range",
                "example": 0.25
              },
              "netSentiment": {
                "type": "number",
                "description": "Net sentiment score (-1 to 1) for the owned brand in the requested date range, based on the balance of endorsed vs undermined feature mentions. Positive values indicate favorable sentiment, negative values indicate unfavorable sentiment",
                "example": 0.42
              }
            },
            "required": [
              "shareOfVoice",
              "netSentiment"
            ]
          }
        ],
        "description": "A prompt with summary performance metrics, returned in list responses"
      },
      "PromptsListResponseData": {
        "type": "object",
        "properties": {
          "prompts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PromptListItem"
            },
            "description": "Array of prompt objects belonging to the specified topic"
          }
        },
        "required": [
          "prompts"
        ]
      },
      "PromptsListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaginatedResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/PromptsListResponseData"
              }
            },
            "required": [
              "data"
            ]
          }
        ],
        "description": "Paginated response containing the list of prompts for a topic"
      },
      "PromptResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Prompt"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing a single prompt"
      },
      "CreatePromptResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "promptId": {
                "type": "string",
                "format": "uuid",
                "description": "Unique identifier of the newly created prompt",
                "example": "550e8400-e29b-41d4-a716-446655440000"
              }
            },
            "required": [
              "promptId"
            ]
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing the ID of the newly created prompt"
      },
      "CreatePromptBody": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "description": "The exact question or statement that will be sent to AI engines for monitoring",
            "example": "What is the best software for small businesses?"
          }
        },
        "required": [
          "query"
        ],
        "description": "Request body for creating a new prompt within a topic"
      },
      "PromptToggleMonitoringBody": {
        "type": "object",
        "properties": {
          "isMonitoringActive": {
            "type": "boolean",
            "description": "Enable or disable automated tracking of AI engine responses for this prompt",
            "example": true
          }
        },
        "required": [
          "isMonitoringActive"
        ],
        "description": "Request body for enabling or disabling prompt monitoring"
      },
      "PromptShareOfVoiceTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/TimeSeriesData"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing all points in the requested time series"
      },
      "PromptVisibilityTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/TimeSeriesData"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing all points in the requested time series"
      },
      "PromptCitationsTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/TimeSeriesData"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing all points in the requested time series"
      },
      "PromptSentimentTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/SentimentTimeSeriesData"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing daily sentiment feature mention distribution for a prompt"
      },
      "Topic": {
        "type": "object",
        "properties": {
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp indicating when the topic was created",
            "example": "2026-01-01T09:30:00Z"
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the topic",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "location": {
            "type": "string",
            "nullable": true,
            "description": "ISO 3166-1 alpha-2 country code for the topic's target market",
            "example": "us"
          },
          "name": {
            "type": "string",
            "description": "The search query or keyword phrase this topic tracks",
            "example": "best software"
          },
          "status": {
            "type": "string",
            "enum": [
              "suggested",
              "imported",
              "custom",
              "active",
              "paused"
            ],
            "description": "Current monitoring status",
            "example": "active"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "User-defined labels for organizing and filtering topics",
            "example": [
              "product",
              "high-priority"
            ]
          },
          "topicSource": {
            "type": "string",
            "nullable": true,
            "enum": [
              "suggested",
              "imported",
              "custom"
            ],
            "description": "How the topic was created",
            "example": "custom"
          },
          "topicType": {
            "type": "string",
            "nullable": true,
            "enum": [
              "Branded",
              "Non-Branded"
            ],
            "description": "Whether the topic contains your brand name (`Branded`) or is a generic query (`Non-Branded`)",
            "example": "Non-Branded"
          }
        },
        "required": [
          "createdAt",
          "id",
          "name",
          "status",
          "tags",
          "topicSource",
          "topicType"
        ],
        "description": "A user topic containing prompts"
      },
      "TopicsListResponseData": {
        "type": "object",
        "properties": {
          "topics": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Topic"
            },
            "description": "Array of topic objects for this brand"
          }
        },
        "required": [
          "topics"
        ]
      },
      "TopicsListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaginatedResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/TopicsListResponseData"
              }
            },
            "required": [
              "data"
            ]
          }
        ],
        "description": "Paginated response containing the list of topics"
      },
      "CreateTopicResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "topicId": {
                "type": "string",
                "format": "uuid",
                "description": "Unique identifier for the newly created topic",
                "example": "550e8400-e29b-41d4-a716-446655440000"
              },
              "promptIds": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Unique identifier for a created prompt",
                  "example": "550e8400-e29b-41d4-a716-446655440001"
                },
                "description": "List of prompt identifiers created for this topic"
              }
            },
            "required": [
              "topicId",
              "promptIds"
            ]
          }
        },
        "required": [
          "data"
        ],
        "description": "Response after successfully creating a topic"
      },
      "CreateTopicBody": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code for the topic's target market",
            "minLength": 2,
            "maxLength": 2,
            "pattern": "^[a-z]{2}$",
            "example": "us"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "The search query or keyword phrase this topic will track",
            "example": "best software"
          },
          "prompts": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            },
            "minItems": 1,
            "description": "List of prompt texts to monitor for this topic",
            "example": [
              "What is the best software for small businesses?",
              "Which tools do you recommend?"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            },
            "description": "Optional list of tags to categorize this topic",
            "example": [
              "product",
              "high-priority"
            ]
          }
        },
        "required": [
          "country",
          "name",
          "prompts"
        ],
        "description": "Request body for creating a new topic"
      },
      "ImportReportSummary": {
        "type": "object",
        "properties": {
          "totalRows": {
            "type": "integer",
            "description": "Total number of rows processed from the CSV"
          },
          "created": {
            "type": "integer",
            "description": "Number of prompts successfully created"
          },
          "skipped": {
            "type": "integer",
            "description": "Number of rows skipped because the prompt already exists"
          },
          "errors": {
            "type": "integer",
            "description": "Number of rows that failed to import due to validation or processing errors"
          },
          "monitoringActivated": {
            "type": "integer",
            "description": "Number of prompts that had monitoring activated during import"
          },
          "monitoringDeactivated": {
            "type": "integer",
            "description": "Number of prompts that had monitoring deactivated during import"
          }
        },
        "required": [
          "totalRows",
          "created",
          "skipped",
          "errors",
          "monitoringActivated",
          "monitoringDeactivated"
        ],
        "description": "Aggregate counts for the import operation"
      },
      "ImportReportTopic": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The topic name that groups the imported prompts",
            "example": "Project Management"
          },
          "country": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code for the topic's target market",
            "example": "us"
          },
          "isNew": {
            "type": "boolean",
            "description": "Whether this topic was created during the import or already existed"
          },
          "promptsCreated": {
            "type": "integer",
            "description": "Number of prompts created under this topic"
          },
          "promptsSkipped": {
            "type": "integer",
            "description": "Number of prompts skipped under this topic because they already existed"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Labels associated with this topic",
            "example": [
              "product",
              "high-priority"
            ]
          }
        },
        "required": [
          "name",
          "country",
          "isNew",
          "promptsCreated",
          "promptsSkipped",
          "tags"
        ],
        "description": "Per-topic breakdown of the import results"
      },
      "ImportReportError": {
        "type": "object",
        "properties": {
          "row": {
            "type": "integer",
            "description": "1-based index of the CSV row that failed"
          },
          "prompt": {
            "type": "string",
            "description": "The prompt text from the failed row",
            "example": "What is the best project management software?"
          },
          "reason": {
            "type": "string",
            "description": "Human-readable explanation of why the row failed",
            "example": "Country code 'xx' is not a valid ISO 3166-1 alpha-2 code"
          }
        },
        "required": [
          "row",
          "prompt",
          "reason"
        ],
        "description": "Details of a row that failed to import"
      },
      "ImportReportSkipped": {
        "type": "object",
        "properties": {
          "row": {
            "type": "integer",
            "description": "1-based index of the CSV row that was skipped"
          },
          "prompt": {
            "type": "string",
            "description": "The prompt text from the skipped row",
            "example": "What is the best project management software?"
          },
          "existingTopicName": {
            "type": "string",
            "description": "Name of the topic that already contained this prompt",
            "example": "Project Management"
          }
        },
        "required": [
          "row",
          "prompt",
          "existingTopicName"
        ],
        "description": "Details of a row that was skipped during import"
      },
      "ImportResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "summary": {
                "$ref": "#/components/schemas/ImportReportSummary"
              },
              "topics": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ImportReportTopic"
                },
                "description": "Per-topic breakdown of created and skipped prompts"
              },
              "errors": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ImportReportError"
                },
                "description": "Rows that failed to import"
              },
              "skipped": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ImportReportSkipped"
                },
                "description": "Rows skipped because the prompt already existed"
              }
            },
            "required": [
              "summary",
              "topics",
              "errors",
              "skipped"
            ]
          }
        },
        "required": [
          "data"
        ],
        "description": "Report summarizing the outcome of a bulk prompt import"
      },
      "ImportRow": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string",
            "minLength": 1,
            "description": "The search query or question to monitor",
            "example": "What is the best project management software?"
          },
          "topic": {
            "type": "string",
            "default": "",
            "description": "Topic name to group this prompt under. Defaults to empty string",
            "example": "Project Management"
          },
          "country": {
            "type": "string",
            "minLength": 1,
            "description": "ISO 3166-1 alpha-2 country code for the prompt's target market",
            "example": "us"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "default": [],
            "description": "Labels for organizing and filtering the imported prompt",
            "example": [
              "product",
              "high-priority"
            ]
          }
        },
        "required": [
          "prompt",
          "country"
        ],
        "description": "A single CSV row representing a prompt to import"
      },
      "ImportRequestBody": {
        "type": "object",
        "properties": {
          "brandId": {
            "type": "string",
            "format": "uuid",
            "description": "The brand to import prompts into",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ImportRow"
            },
            "minItems": 1,
            "maxItems": 2000,
            "description": "Parsed CSV rows to import"
          }
        },
        "required": [
          "brandId",
          "rows"
        ],
        "description": "Request body for bulk prompt import"
      },
      "TopicResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Topic"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing a single topic"
      },
      "TopicToggleMonitoringBody": {
        "type": "object",
        "properties": {
          "isMonitoringActive": {
            "type": "boolean",
            "description": "Enable or disable automated tracking of AI engine responses for this topic and all its associated prompts. When active, all prompts within the topic are monitored",
            "example": true
          }
        },
        "required": [
          "isMonitoringActive"
        ],
        "description": "Request body for enabling or disabling monitoring for a topic. This action affects all prompts belonging to the topic"
      },
      "TopicShareOfVoiceTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/TimeSeriesData"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing all points in the requested time series"
      },
      "TopicVisibilityTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/TimeSeriesData"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing all points in the requested time series"
      },
      "TopicCitationsTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/TimeSeriesData"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing all points in the requested time series"
      },
      "TopicSentimentTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/SentimentTimeSeriesData"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing daily sentiment feature mention distribution for a topic"
      },
      "Trend": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the trend",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "name": {
            "type": "string",
            "description": "The search query or topic keyword being tracked",
            "example": "best software of 2026"
          },
          "location": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code for the prompt's target market",
            "example": "us"
          },
          "metrics": {
            "type": "object",
            "properties": {
              "timeseries": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "date": {
                      "type": "string",
                      "format": "date",
                      "description": "ISO 8601 date for this data point",
                      "example": "2026-01-01"
                    },
                    "searchVolume": {
                      "type": "number",
                      "minimum": 0,
                      "exclusiveMinimum": true,
                      "description": "Monthly search volume for this date",
                      "example": 12500
                    }
                  },
                  "required": [
                    "date",
                    "searchVolume"
                  ]
                }
              },
              "searchVolume": {
                "type": "number",
                "minimum": 0,
                "exclusiveMinimum": true,
                "description": "Average monthly search volume across all data points in the timeseries. Indicates overall search demand for this topic",
                "example": 15000
              },
              "relativeCompetition": {
                "type": "string",
                "enum": [
                  "LOW",
                  "MEDIUM",
                  "HIGH"
                ],
                "description": "Difficulty level for ranking on this topic, adjusted relative to the brand's domain authority. LOW = easier to rank, HIGH = more competitive",
                "example": "MEDIUM"
              },
              "relativeCompetitionIndex": {
                "type": "number",
                "minimum": 0,
                "exclusiveMinimum": true,
                "description": "Numeric competition score (0-100) normalized for the brand's market position. Higher values indicate more competitive topics",
                "example": 65
              }
            },
            "required": [
              "timeseries",
              "searchVolume"
            ]
          },
          "prompts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Unique identifier for the prompt",
                  "example": "550e8400-e29b-41d4-a716-446655440001"
                },
                "name": {
                  "type": "string",
                  "description": "The exact search query associated with this trend",
                  "example": "What is the best software tool for teams?"
                }
              },
              "required": [
                "id",
                "name"
              ]
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "suggested",
              "imported",
              "custom",
              "active",
              "paused"
            ],
            "description": "Current monitoring status of the trend.",
            "example": "active"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "User-defined labels for organizing and filtering trends",
            "example": [
              "product",
              "high-priority"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "location",
          "metrics",
          "prompts",
          "status",
          "tags"
        ],
        "description": "A trend that can be transformed into a tracked topic"
      },
      "TrendsListResponseData": {
        "type": "object",
        "properties": {
          "trends": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Trend"
            },
            "description": "Array of trend topics for the brand"
          }
        },
        "required": [
          "trends"
        ]
      },
      "TrendsListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaginatedResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/TrendsListResponseData"
              }
            },
            "required": [
              "data"
            ]
          }
        ],
        "description": "Paginated response containing the list of trends"
      },
      "TrendsImportResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "imported": {
                "type": "number",
                "description": "Number of keywords that have been successfully imported",
                "example": 7
              },
              "skipped": {
                "type": "number",
                "description": "Number of keywords that have been skipped",
                "example": 2
              }
            },
            "required": [
              "imported",
              "skipped"
            ]
          }
        },
        "required": [
          "data"
        ],
        "description": "Response to trend import using keywords"
      },
      "TrendStartMonitoringResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "topicId": {
                "type": "string",
                "format": "uuid",
                "description": "Generated topic id",
                "example": "550e8400-e29b-41d4-a716-446655440001"
              }
            },
            "required": [
              "topicId"
            ]
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing the generated topic id"
      },
      "TrendStartMonitoringBody": {
        "type": "object",
        "properties": {
          "promptIds": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid",
              "description": "Prompt id",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "minItems": 1
          }
        },
        "required": [
          "promptIds"
        ],
        "description": "Request body for accepting a trend. This action starts monitoring only prompts included in this request"
      },
      "ViewFilters": {
        "type": "object",
        "properties": {
          "promptType": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ]
            },
            "description": "Prompt types to include. `Branded` prompts mention your brand name; `Non-Branded` prompts are generic queries. Applied only when exactly one type is selected — selecting both is equivalent to no filter.",
            "example": [
              "Branded"
            ]
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            },
            "description": "ISO 3166-1 alpha-2 country codes of the prompts' target markets to include",
            "example": [
              "us",
              "de"
            ]
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "active",
                "paused"
              ]
            },
            "description": "Monitoring status to filter by. `active` matches prompts with monitoring on, `paused` matches prompts with monitoring off. Applied only when exactly one value is selected.",
            "example": [
              "active"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "User-defined tags to filter prompts by",
            "example": [
              "product",
              "high-priority"
            ]
          },
          "tagsMatchMode": {
            "type": "string",
            "enum": [
              "all",
              "any"
            ],
            "description": "How to match tags: 'any' includes prompts with at least one selected tag (OR), 'all' includes prompts with every selected tag (AND). Defaults to 'any'.",
            "example": "any"
          }
        },
        "additionalProperties": false,
        "description": "Saved prompt filters defining which of the brand's prompts the view groups. All criteria combine with AND."
      },
      "View": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the view",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "brandId": {
            "type": "string",
            "format": "uuid",
            "description": "Identifier of the brand the view belongs to",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name of the view, unique per brand (case-insensitive)",
            "example": "US branded prompts"
          },
          "filters": {
            "$ref": "#/components/schemas/ViewFilters"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp indicating when the view was created",
            "example": "2026-01-01T09:30:00Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp indicating when the view was last updated",
            "example": "2026-01-01T09:30:00Z"
          }
        },
        "required": [
          "id",
          "brandId",
          "name",
          "filters",
          "createdAt",
          "updatedAt"
        ],
        "description": "A named saved filter over a brand's prompts. Views group prompts dynamically: the prompt set is resolved from the filters at query time."
      },
      "ViewsListResponseData": {
        "type": "object",
        "properties": {
          "views": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/View"
            },
            "description": "Array of views belonging to the specified brand"
          }
        },
        "required": [
          "views"
        ]
      },
      "ViewsListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaginatedResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/ViewsListResponseData"
              }
            },
            "required": [
              "data"
            ]
          }
        ],
        "description": "Paginated response containing the list of views for a brand"
      },
      "ViewResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/View"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing a single view"
      },
      "CreateViewBody": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "Name for the view, unique per brand (case-insensitive)",
            "example": "US branded prompts"
          },
          "filters": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ViewFilters"
              },
              {
                "default": {},
                "description": "Prompt filters for the view. Omit for a view matching all prompts."
              }
            ]
          }
        },
        "required": [
          "name"
        ],
        "description": "Request body for creating a view"
      },
      "PatchViewBody": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "New name for the view, unique per brand (case-insensitive)",
            "example": "US branded prompts"
          },
          "filters": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ViewFilters"
              },
              {
                "description": "New prompt filters for the view. Replaces the entire filters object."
              }
            ]
          }
        },
        "description": "Request body for updating a view"
      },
      "ViewVisibilityTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/TimeSeriesData"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing all points in the requested time series"
      },
      "ViewShareOfVoiceTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/TimeSeriesData"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing all points in the requested time series"
      },
      "ViewCitationsTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/TimeSeriesData"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing all points in the requested time series"
      },
      "ViewSentimentTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/SentimentTimeSeriesData"
          }
        },
        "required": [
          "data"
        ],
        "description": "Response containing daily sentiment feature mention distribution for a view"
      }
    },
    "parameters": {}
  },
  "paths": {
    "/api/v1/prompts/{prompt}/ai-answers": {
      "get": {
        "operationId": "list-prompt-ai-answers",
        "description": "Retrieve a paginated list of AI answers for the given prompt. Pagination in this endpoint is not 100% accurate and pages might have fewer items than initially requested. For the same reason, the real total number of items can be lower than the one reported in responses",
        "summary": "List AI answers",
        "tags": [
          "AI Answer"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the prompt",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "prompt",
            "in": "path"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter results by specific AI engine. Omit to return answers from all supported engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "created_at",
                "execution_date",
                "share_of_voice",
                "mentioned",
                "engine_id"
              ],
              "description": "Field to sort results by",
              "example": "created_at"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc",
              "description": "Direction to sort results",
              "example": "desc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter to only show answers where the tracked brand was mentioned",
              "example": "true"
            },
            "required": false,
            "name": "mentioned",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of normalized brand names to filter by. Only answers mentioning these brands are returned. Use the availableBrands keys from filterOptions in the response to discover valid values",
              "example": "nike,adidas"
            },
            "required": false,
            "name": "mentionedBrands",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of domains to filter by. Only answers citing these domains are returned. Use availableCitations from filterOptions in the response to discover valid values",
              "example": "example.com,acme.com"
            },
            "required": false,
            "name": "citations",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter by feature attribution using colon-delimited format: featureName:brandName:sentiment. At least one segment must be provided. Segments can be omitted from the right, or left empty to skip. All values must be normalized (lowercased, no diacritics or special characters). Valid sentiment values: endorsed, undermined, neutral. Use availableFeatures from filterOptions in the response to discover valid features. Examples: 'pricing' (feature only), 'pricing:acme' (feature + brand), 'pricing:acme:endorsed' (all three), '::undermined' (sentiment only), ':acme:endorsed' (brand + sentiment)",
              "example": "pricing:acme:endorsed"
            },
            "required": false,
            "name": "featureAttribution",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved AI answers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiAnswersListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/ai-answers/{ai-answer}": {
      "get": {
        "operationId": "get-ai-answer",
        "description": "Retrieve one AI answer by its id: the full response an AI engine gave to a monitored prompt, with the sources it cited. Use it to read the wording behind a metric or a citation.",
        "summary": "Get AI answer",
        "tags": [
          "AI Answer"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Unique identifier for the AI answer"
            },
            "required": true,
            "name": "ai-answer",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved AI answer",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiAnswerResponse"
                },
                "example": {
                  "data": {
                    "answer": "Based on my analysis, the best software for small businesses includes Brand 1, Brand 2, and Brand 3...",
                    "citations": [
                      {
                        "title": "Best Software 2026 | Acme Reviews",
                        "url": "https://example.com/software-reviews"
                      }
                    ],
                    "createdAt": "2026-01-01T09:30:00Z",
                    "engine": "openai",
                    "id": 12345,
                    "mentioned": true,
                    "mentionedBrands": [
                      "Brand 1",
                      "Brand 2",
                      "Brand 3"
                    ],
                    "promptId": "550e8400-e29b-41d4-a716-446655440000",
                    "query": "What is the best software for small businesses?"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands": {
      "get": {
        "operationId": "list-brands",
        "description": "Retrieve a paginated list of brands. Optionally filter by domain or name using partial, case-insensitive matching.",
        "summary": "List brands",
        "tags": [
          "Brand"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter brands by domain (partial match, case-insensitive)",
              "example": "example.com"
            },
            "required": false,
            "name": "domain",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter brands by name (partial match, case-insensitive)",
              "example": "Acme"
            },
            "required": false,
            "name": "name",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved brands",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandsListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "create-brand",
        "description": "Create a new brand with the provided details. The brand will be associated with the authenticated organization.",
        "summary": "Create brand",
        "tags": [
          "Brand"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBrandBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created brand",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateBrandResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands/{brand}": {
      "get": {
        "operationId": "get-brand",
        "description": "Retrieve one brand by its id, with its domain, alternative names, markets and tracked competitors. Use it to turn a brand id into the brand details the analytics endpoints report on.",
        "summary": "Get brand",
        "tags": [
          "Brand"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved brand",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandResponse"
                },
                "example": {
                  "data": {
                    "id": "550e8400-e29b-41d4-a716-446655440000",
                    "name": "Acme Corporation",
                    "domain": "acme.com",
                    "slug": "acme",
                    "mainLocation": "us",
                    "createdAt": "2026-01-01T09:30:00Z",
                    "setupCompletedAt": "2026-01-01T09:30:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "update-brand",
        "description": "Update an existing brand. Only the fields provided in the request body will be updated.",
        "summary": "Update brand",
        "tags": [
          "Brand"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateBrandBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully updated brand",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "delete-brand",
        "description": "Delete a brand and all its associated data including topics and prompts. This action cannot be undone.",
        "summary": "Delete brand",
        "tags": [
          "Brand"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Successfully deleted brand"
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands/{brand}/share-of-voice/aggregates": {
      "get": {
        "operationId": "get-brand-share-of-voice-aggregates",
        "description": "Retrieve share of voice for a brand and its competitors over a date range: the portion of all brand mentions in the AI answers to the brand's monitored prompts that each brand holds. Use it to compare brands against each other for a period.",
        "summary": "Get share of voice aggregates",
        "tags": [
          "Brand Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of ISO 3166-1 alpha-2 country codes",
              "example": "us,gb,de"
            },
            "required": false,
            "name": "locations",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "nullable": true,
              "description": "Comma-separated list of tags to filter results",
              "example": "product,high-priority"
            },
            "required": false,
            "name": "tags",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by topic type (deprecated — use promptType instead)",
              "example": "Non-Branded",
              "deprecated": true
            },
            "required": false,
            "name": "topicType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by prompt type",
              "example": "Non-Branded"
            },
            "required": false,
            "name": "promptType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc",
              "description": "Direction to sort results",
              "example": "asc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter results by brand name",
              "example": "Acme Corporation"
            },
            "required": false,
            "name": "brandName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "rank",
                "share_of_voice",
                "mentions"
              ],
              "default": "rank",
              "description": "Field to sort results by",
              "example": "rank"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShareOfVoiceAggregatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands/{brand}/share-of-voice/timeseries": {
      "get": {
        "operationId": "get-brand-share-of-voice-timeseries",
        "description": "Retrieve time series data showing share of voice evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range.",
        "summary": "Get share of voice time series",
        "tags": [
          "Brand Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of ISO 3166-1 alpha-2 country codes",
              "example": "us,gb,de"
            },
            "required": false,
            "name": "locations",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "nullable": true,
              "description": "Comma-separated list of tags to filter results",
              "example": "product,high-priority"
            },
            "required": false,
            "name": "tags",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by topic type (deprecated — use promptType instead)",
              "example": "Non-Branded",
              "deprecated": true
            },
            "required": false,
            "name": "topicType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by prompt type",
              "example": "Non-Branded"
            },
            "required": false,
            "name": "promptType",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved time series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandShareOfVoiceTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands/{brand}/visibility/aggregates": {
      "get": {
        "operationId": "get-brand-visibility-aggregates",
        "description": "Retrieve visibility for a brand and its competitors over a date range: the share of the brand's monitored prompts whose AI answers mention each brand. Use it to see how often a brand appears at all for a period.",
        "summary": "Get visibility aggregates",
        "tags": [
          "Brand Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of ISO 3166-1 alpha-2 country codes",
              "example": "us,gb,de"
            },
            "required": false,
            "name": "locations",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "nullable": true,
              "description": "Comma-separated list of tags to filter results",
              "example": "product,high-priority"
            },
            "required": false,
            "name": "tags",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by topic type (deprecated — use promptType instead)",
              "example": "Non-Branded",
              "deprecated": true
            },
            "required": false,
            "name": "topicType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by prompt type",
              "example": "Non-Branded"
            },
            "required": false,
            "name": "promptType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc",
              "description": "Direction to sort results",
              "example": "asc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter results by brand name",
              "example": "Acme Corporation"
            },
            "required": false,
            "name": "brandName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "rank",
                "visibility"
              ],
              "default": "rank",
              "description": "Field to sort results by",
              "example": "rank"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VisibilityAggregatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands/{brand}/visibility/timeseries": {
      "get": {
        "operationId": "get-brand-visibility-timeseries",
        "description": "Retrieve time series data showing visibility evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range.",
        "summary": "Get visibility time series",
        "tags": [
          "Brand Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of ISO 3166-1 alpha-2 country codes",
              "example": "us,gb,de"
            },
            "required": false,
            "name": "locations",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "nullable": true,
              "description": "Comma-separated list of tags to filter results",
              "example": "product,high-priority"
            },
            "required": false,
            "name": "tags",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by topic type (deprecated — use promptType instead)",
              "example": "Non-Branded",
              "deprecated": true
            },
            "required": false,
            "name": "topicType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by prompt type",
              "example": "Non-Branded"
            },
            "required": false,
            "name": "promptType",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved time series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandVisibilityTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands/{brand}/citations/aggregates": {
      "get": {
        "operationId": "get-brand-citations-aggregates",
        "description": "Retrieve the web sources cited by the AI answers to a brand's monitored prompts over a date range, with how often each source is cited. Use it to find which pages AI engines draw on when they answer.",
        "summary": "Get citations aggregates",
        "tags": [
          "Brand Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of ISO 3166-1 alpha-2 country codes",
              "example": "us,gb,de"
            },
            "required": false,
            "name": "locations",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "nullable": true,
              "description": "Comma-separated list of tags to filter results",
              "example": "product,high-priority"
            },
            "required": false,
            "name": "tags",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by topic type (deprecated — use promptType instead)",
              "example": "Non-Branded",
              "deprecated": true
            },
            "required": false,
            "name": "topicType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by prompt type",
              "example": "Non-Branded"
            },
            "required": false,
            "name": "promptType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc",
              "description": "Direction to sort results",
              "example": "desc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter by source domain name",
              "example": "example.com"
            },
            "required": false,
            "name": "sourceName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "owned",
                "third_party",
                "social"
              ],
              "description": "Filter by citation ownership type",
              "example": "owned"
            },
            "required": false,
            "name": "sourceType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "total_citations"
              ],
              "default": "total_citations",
              "description": "Field to sort results by",
              "example": "total_citations"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CitationsAggregatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands/{brand}/citations/timeseries": {
      "get": {
        "operationId": "get-brand-citations-timeseries",
        "description": "Retrieve time series data showing citations evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range.",
        "summary": "Get citations time series",
        "tags": [
          "Brand Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of ISO 3166-1 alpha-2 country codes",
              "example": "us,gb,de"
            },
            "required": false,
            "name": "locations",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "nullable": true,
              "description": "Comma-separated list of tags to filter results",
              "example": "product,high-priority"
            },
            "required": false,
            "name": "tags",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by topic type (deprecated — use promptType instead)",
              "example": "Non-Branded",
              "deprecated": true
            },
            "required": false,
            "name": "topicType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by prompt type",
              "example": "Non-Branded"
            },
            "required": false,
            "name": "promptType",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved time series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandCitationsTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands/{brand}/sentiment/timeseries": {
      "get": {
        "operationId": "get-brand-sentiment-timeseries",
        "description": "Retrieve daily sentiment distribution over time for the owned brand only (competitors are not included). Returns counts of endorsed, undermined, and neutral feature mentions per day within the specified date range.",
        "summary": "Get sentiment time series",
        "tags": [
          "Brand Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of ISO 3166-1 alpha-2 country codes",
              "example": "us,gb,de"
            },
            "required": false,
            "name": "locations",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "nullable": true,
              "description": "Comma-separated list of tags to filter results",
              "example": "product,high-priority"
            },
            "required": false,
            "name": "tags",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by topic type (deprecated — use promptType instead)",
              "example": "Non-Branded",
              "deprecated": true
            },
            "required": false,
            "name": "topicType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by prompt type",
              "example": "Non-Branded"
            },
            "required": false,
            "name": "promptType",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved sentiment time series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandSentimentTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands/{brand}/sentiment/aggregates": {
      "get": {
        "operationId": "get-brand-sentiment-aggregates",
        "description": "Retrieve a flat, paginated list of sentiment aggregates. Each row represents a unique brand-feature pair with counts of endorsed, undermined, and neutral feature mentions.",
        "summary": "Get sentiment aggregates",
        "tags": [
          "Brand Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of ISO 3166-1 alpha-2 country codes",
              "example": "us,gb,de"
            },
            "required": false,
            "name": "locations",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "nullable": true,
              "description": "Comma-separated list of tags to filter results",
              "example": "product,high-priority"
            },
            "required": false,
            "name": "tags",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by topic type (deprecated — use promptType instead)",
              "example": "Non-Branded",
              "deprecated": true
            },
            "required": false,
            "name": "topicType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by prompt type",
              "example": "Non-Branded"
            },
            "required": false,
            "name": "promptType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter results by brand name",
              "example": "Acme Corporation"
            },
            "required": false,
            "name": "brandName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter results by feature name",
              "example": "customer support"
            },
            "required": false,
            "name": "featureName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "rank",
                "total_mentions",
                "endorsed_mentions",
                "undermined_mentions",
                "neutral_mentions"
              ],
              "default": "rank",
              "description": "Field to sort results by",
              "example": "rank"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc",
              "description": "Direction to sort results",
              "example": "asc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved sentiment aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SentimentAggregatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands/{brand}/export": {
      "get": {
        "operationId": "stream-brand-metrics",
        "summary": "Stream metrics export",
        "tags": [
          "Brand Performance"
        ],
        "description": "Stream every row of the selected metric for the given brand. Changing `entity` cascades entity information onto each row: brand-level exports carry only brand fields, topic-level exports also include the topic, and prompt-level exports also include the prompt.\n      \nIf you can't keep an HTTP connection open for the duration of the export (for example, for scheduled jobs, very large date ranges, or background pipelines), use `POST /api/v1/brands/{brand}/export` instead and poll for completion.\n\n\n> [!note]\n> This endpoint streams its response as **newline-delimited JSON (NDJSON)**. Each line of the response body is a self-contained JSON object matching the schema below. There is no pagination, the full filtered dataset is returned in one long-lived HTTP connection. Learn more about streaming responses [here](#description/streaming-responses-ndjson).\n\n\n> [!important]\n> Calling this endpoint uses **25 tokens** from your rate limit bucket. Learn more about rate limiting [here](#description/rate-limiting).\n",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "brand",
                "prompt",
                "topic"
              ],
              "description": "The granularity of the exported data"
            },
            "required": true,
            "name": "entity",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "share-of-voice",
                "visibility",
                "citations"
              ],
              "description": "Name of the metric to be exported"
            },
            "required": true,
            "name": "metric",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "A stream of NDJSON rows. Each line is a JSON object matching one of the `ExportRow` variants.",
            "content": {
              "application/x-ndjson": {
                "schema": {
                  "$ref": "#/components/schemas/ExportRow"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "create-brand-metrics-export",
        "summary": "Create metrics export task",
        "tags": [
          "Brand Performance"
        ],
        "description": "Schedule an asynchronous export task that writes the resulting **ZIP archive** to cloud storage and exposes it as a presigned download URL. Use this variant when you don't want to keep an HTTP connection open for the duration of the export (for example, for scheduled jobs, very large date ranges, or background pipelines) or when you need files ready to load into BI tools like Looker Studio, BigQuery or Tableau.\n\nThe request body is empty; all parameters are passed as query parameters. The date range and the engine filter behave exactly as on the streaming `GET` variant. Where the `GET` takes a single `entity` and `metric`, this endpoint takes comma-separated `entities` and `metrics` so one task can cover several granularities and metrics at once, plus a `format` selecting how each file is serialized.\n\nThe archive holds **one file per requested `entities` × `metrics` combination**, named `<entity>_<metric>.<format>` — for example `prompt_share-of-voice.ndjson`. If any individual query fails, the archive also contains an `errors.json` listing the combinations that could not be produced, and the task reports `status: \"failed\"`.\n\n`format` selects how each file is serialized:\n\n- `ndjson` (default) — one JSON object per line, matching the `ExportRow` shape documented on the streaming endpoint. Fields that have no value are omitted from the line.\n- `csv` — a header row followed by one row per record. The columns are the `ExportRow` fields for the requested entity and metric, sorted alphabetically and identical on every row; a field with no value is written as an empty cell. Columns are fixed by the schema, so the header is present even when the export contains no rows.\n\nThe response is `202 Accepted` with `links.self` pointing at the polling endpoint (`GET /api/v1/exports/{export}`). Poll that URL until the `status` becomes `completed` (or `failed`). When the export completes, the polling response includes a `resultsUrl`, a presigned URL that lets you download the archive. Presigned URLs expire 7 days after generation.\n\n\n> [!note]\n> This is a long-running operation. The response includes a `links.self` URL you can use to keep track of the status of the operation. Learn more about async endpoints [here](#description/async-operations).\n\n\n> [!important]\n> Calling this endpoint uses **25 tokens** from your rate limit bucket. Learn more about rate limiting [here](#description/rate-limiting).\n",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Array of different granularities to be exported. Defaults to all granularities available to the caller.",
              "enum": [
                "brand",
                "prompt",
                "topic"
              ]
            },
            "required": false,
            "name": "entities",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "default": "share-of-voice,visibility,citations",
              "description": "Array of the different metrics to be exported",
              "enum": [
                "share-of-voice",
                "visibility",
                "citations"
              ]
            },
            "required": false,
            "name": "metrics",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "ndjson",
                "csv"
              ],
              "default": "ndjson",
              "description": "The format of the resulting exported files"
            },
            "required": false,
            "name": "format",
            "in": "query"
          }
        ],
        "responses": {
          "202": {
            "description": "Successfully scheduled the metrics export task",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateExportResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands/{brand}/prompts": {
      "post": {
        "operationId": "create-brand-prompts",
        "description": "Bulk-create prompts for a brand. Each prompt is grouped under the named topic, or an auto-managed topic for the given location if no topic name is provided. Returns a report detailing created prompts, skipped duplicates, and row-level errors.",
        "summary": "Create prompts",
        "tags": [
          "Prompt"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBrandPromptsBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created prompts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateBrandPromptsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "list-brand-prompts",
        "description": "Retrieve every prompt monitored for a brand, with its text, type, country, tags and monitoring status. Use it to find the prompt a caller is asking about, or to review what the brand currently tracks.",
        "summary": "List brand prompts",
        "tags": [
          "Prompt"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for sorting data (ISO 8601 date format). Defaults to 7 days ago. Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": false,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for sorting data (ISO 8601 date format). Defaults to today. Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": false,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of ISO 3166-1 alpha-2 country codes to filter prompts by target market",
              "example": "us,gb,de"
            },
            "required": false,
            "name": "countries",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter results by specific AI engine. Omit to return prompts for all supported engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "name",
                "share_of_voice",
                "net_sentiment",
                "updated_at",
                "country"
              ],
              "default": "updated_at",
              "description": "Field to sort prompts by",
              "example": "updated_at"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc",
              "description": "Sort order direction",
              "example": "desc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "paused"
              ],
              "description": "Filter by prompt lifecycle status",
              "example": "active"
            },
            "required": false,
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "nullable": true,
              "description": "Comma-separated list of user-defined tags to filter prompts",
              "example": "product,high-priority"
            },
            "required": false,
            "name": "tags",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "any"
              ],
              "description": "How to match tags: 'any' returns prompts with at least one selected tag (OR), 'all' returns prompts with every selected tag (AND). Defaults to 'any'.",
              "example": "any"
            },
            "required": false,
            "name": "tagsMatchMode",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by prompt type. `Branded` prompts mention your brand name; `Non-Branded` prompts are generic queries.",
              "example": "Branded"
            },
            "required": false,
            "name": "type",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved prompts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandPromptsListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/exports/{export}": {
      "get": {
        "operationId": "get-metrics-export",
        "description": "Retrieve the status of a metrics export task. When the export has finished successfully, the response includes a presigned URL to download the results as a ZIP archive, holding one file per exported entity and metric in the `format` requested when the task was created. While the task is in progress, the response includes a `Retry-After` header suggesting when to poll again.",
        "summary": "Get metrics export",
        "tags": [
          "Brand Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the metrics export",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "export",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved metrics export",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricsExportResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands/{brand}/insights": {
      "get": {
        "operationId": "list-brand-insights",
        "description": "Retrieve the insights generated for a brand's prompts, newest first. Use it to read the written explanations of why the brand performs the way it does, rather than the metrics themselves.",
        "summary": "List insights",
        "tags": [
          "Insight"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of insights to return per page",
              "example": 20
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "action",
                "monitor"
              ],
              "description": "Filter insights by type",
              "example": "action"
            },
            "required": false,
            "name": "type",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter insights by AI engine name",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Filter insights to those associated with a specific prompt",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": false,
            "name": "promptId",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of statuses to filter by (OR logic: matches insights with ANY of the provided statuses). When omitted, insights are returned regardless of status.",
              "example": "open,completed"
            },
            "required": false,
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Case-insensitive partial match against the insight title. When omitted, no text filtering is applied.",
              "example": "content gap"
            },
            "required": false,
            "name": "search",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of impact levels to filter by (OR logic: matches insights with ANY of the provided levels). When omitted, insights are returned regardless of impact.",
              "example": "low,medium"
            },
            "required": false,
            "name": "impact",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering insights (ISO 8601 date format, inclusive)",
              "example": "2026-01-01"
            },
            "required": false,
            "name": "dateFrom",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering insights (ISO 8601 date format, exclusive)",
              "example": "2026-01-31"
            },
            "required": false,
            "name": "dateTo",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved insights",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InsightsListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/insights/{insight}": {
      "get": {
        "operationId": "get-insight",
        "description": "Retrieve one insight by its id, with its full text and the prompt it was generated from. Use it to read an insight a list call referred to.",
        "summary": "Get insight",
        "tags": [
          "Insight"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the insight",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "insight",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved insight",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InsightResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "update-insight",
        "description": "Change the status of one insight. Use it to record that a caller has acted on an insight or no longer wants to see it.",
        "summary": "Update insight",
        "tags": [
          "Insight"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the insight",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "insight",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PatchInsightBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully updated insight",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InsightResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/prompts/{prompt}/insights": {
      "post": {
        "deprecated": true,
        "operationId": "create-prompt-insights",
        "description": "Starts a new insights generation task.\n\n**Deprecated**: Insight generation ends on November 2, 2026, after which this endpoint returns a `410 Gone` error. To improve a prompt's visibility or sentiment, run the `improve-prompt-metrics` skill in Omnia Agent instead.\n      \n\n> [!note]\n> This is a long-running operation. The response includes a `links.self` URL you can use to keep track of the status of the operation. Learn more about async endpoints [here](#description/async-operations).\n\n\n> [!important]\n> Calling this endpoint uses **25 tokens** from your rate limit bucket. Learn more about rate limiting [here](#description/rate-limiting).\n",
        "summary": "Generate insights",
        "tags": [
          "Insight Generation"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the prompt",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "prompt",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateInsightBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully started insights generation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateInsightResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Duplicated item",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1008
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Duplicated item"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/insights/generations/{generation}": {
      "get": {
        "operationId": "get-insight-generation",
        "description": "Retrieve an insight generation by its id. This method is used to poll ongoing generations.",
        "summary": "Get insight generation",
        "tags": [
          "Insight Generation"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the insight generation",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "generation",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved insight generation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InsightGenerationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands/{brand}/projects": {
      "get": {
        "operationId": "list-brand-projects",
        "description": "Retrieve the Projects on a brand's board, newest first. Use it to review the brand's work: what Omnia Agent suggested and what is planned, in progress or done. To read one Project by its reference, use get-project.",
        "summary": "List Projects",
        "tags": [
          "Project"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of statuses to keep (matches Projects in ANY of them). `suggested` Projects are Omnia Agent's proposals that have not been accepted yet. When omitted, Projects in every status are returned.",
              "example": "to_do,in_progress"
            },
            "required": false,
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false",
              "description": "`false` returns the Projects on the board; `true` returns only the discarded ones.",
              "example": "false"
            },
            "required": false,
            "name": "discarded",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Keep only the Project with this reference (case-insensitive)",
              "pattern": "^[Pp][Rr][Jj]-[1-9][0-9]*$",
              "example": "PRJ-42"
            },
            "required": false,
            "name": "reference",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved Projects",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandProjectsListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "create-project",
        "description": "Create a Project on a brand's board. A Project is one concrete piece of work to improve a brand's visibility in AI answers, scoped so it can be finished and closed with an outcome. Use it to add work to the board, such as work planned outside Omnia. Returns the Project as get-project does.",
        "summary": "Create Project",
        "tags": [
          "Project"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateProjectBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created Project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/projects/{project}": {
      "get": {
        "operationId": "get-project",
        "description": "Retrieve one Project with its full description. Use it to read a Project a list call returned, or one known by its reference (PRJ-n). To read the files in it, use list-project-files.",
        "summary": "Get Project",
        "tags": [
          "Project"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "The Project's id, or its reference (`PRJ-42`) together with `brand`. A reference is case-insensitive.",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "project",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Brand the Project belongs to. Required when `project` is a reference, since each brand numbers its Projects from PRJ-1; ignored when `project` is an id.",
              "example": "550e8400-e29b-41d4-a716-446655440001"
            },
            "required": false,
            "name": "brand",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved Project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "update-project",
        "description": "Change one Project: move it to another status (`done` closes it, optionally with an `outcomeSummary`), discard it, restore it, rewrite any of its headline, summary and body, or set its Category. Every field sent is applied together, in one change; if any part is refused, nothing is changed. Fields combine freely, except `discarded: true` with `status`. A discarded Project keeps its content and Category editable, but must be restored before it moves, which can happen in the same call. Fields left out stay as they are, and a call that changes nothing returns the Project unchanged. Use it to record progress made outside Omnia and to keep the brief current as the work takes shape.",
        "summary": "Update Project",
        "tags": [
          "Project"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "The Project's id, or its reference (`PRJ-42`) together with `brand`. A reference is case-insensitive.",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "project",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Brand the Project belongs to. Required when `project` is a reference, since each brand numbers its Projects from PRJ-1; ignored when `project` is an id.",
              "example": "550e8400-e29b-41d4-a716-446655440001"
            },
            "required": false,
            "name": "brand",
            "in": "query"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PatchProjectBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully updated Project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "The item's current state does not allow this change",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1014
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "The item's current state does not allow this change"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/projects/{project}/files": {
      "get": {
        "operationId": "list-project-files",
        "description": "Retrieve the files in a Project: what Omnia Agent delivered while working on it and what the user uploaded, the latest version of each. Each file comes with a signed `url` that downloads its content until `urlsExpireAt`; fetch it to read the file, and list again for fresh URLs once they expire.",
        "summary": "List Project Files",
        "tags": [
          "Project"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "The Project's id, or its reference (`PRJ-42`) together with `brand`. A reference is case-insensitive.",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "project",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Brand the Project belongs to. Required when `project` is a reference, since each brand numbers its Projects from PRJ-1; ignored when `project` is an id.",
              "example": "550e8400-e29b-41d4-a716-446655440001"
            },
            "required": false,
            "name": "brand",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved the Project's files",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectFilesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/topics/{topic}/prompts": {
      "get": {
        "deprecated": true,
        "operationId": "list-topic-prompts",
        "description": "Retrieve a paginated list of prompts.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/prompts` instead. It does not require a topic ID and supports `type`, `countries`, and `tags` filters to narrow the results.",
        "summary": "List prompts",
        "tags": [
          "Prompt"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the topic",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "topic",
            "in": "path"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for sorting data (ISO 8601 date format). Defaults to 7 days ago. Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": false,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for sorting data (ISO 8601 date format). Defaults to today. Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": false,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of ISO 3166-1 alpha-2 country codes to filter prompts by target market",
              "example": "us,gb,de"
            },
            "required": false,
            "name": "countries",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter results by specific AI engine. Omit to return prompts for all supported engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "name",
                "share_of_voice",
                "net_sentiment",
                "updated_at",
                "country"
              ],
              "default": "updated_at",
              "description": "Field to sort prompts by",
              "example": "updated_at"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc",
              "description": "Sort order direction",
              "example": "desc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "paused"
              ],
              "description": "Filter by prompt lifecycle status",
              "example": "active"
            },
            "required": false,
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "nullable": true,
              "description": "Comma-separated list of user-defined tags to filter prompts",
              "example": "product,high-priority"
            },
            "required": false,
            "name": "tags",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "any"
              ],
              "description": "How to match tags: 'any' returns prompts with at least one selected tag (OR), 'all' returns prompts with every selected tag (AND). Defaults to 'any'.",
              "example": "any"
            },
            "required": false,
            "name": "tagsMatchMode",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved prompts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromptsListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "deprecated": true,
        "operationId": "create-topic-prompt",
        "description": "Creates a new non-monitored prompt that depends on the selected topic.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `POST /api/v1/brands/{brand}/prompts` instead. It does not require a topic ID.",
        "summary": "Create prompt",
        "tags": [
          "Prompt"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the topic",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "topic",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePromptBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created prompt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatePromptResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Duplicated item",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1008
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Duplicated item"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/prompts/{prompt}": {
      "get": {
        "operationId": "get-prompt",
        "description": "Retrieve one prompt by its id, with its text, type, country, tags and monitoring status. Use it to turn a prompt id into the prompt's own configuration.",
        "summary": "Get prompt",
        "tags": [
          "Prompt"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the prompt",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "prompt",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved prompt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromptResponse"
                },
                "example": {
                  "data": {
                    "createdAt": "2026-01-01T09:30:00Z",
                    "id": "550e8400-e29b-41d4-a716-446655440000",
                    "isMonitoringActive": true,
                    "location": "us",
                    "query": "What is the best software for small businesses?",
                    "tags": [
                      "product",
                      "high-priority"
                    ],
                    "topicId": "550e8400-e29b-41d4-a716-446655440001",
                    "type": "Non-Branded"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "update-prompt",
        "description": "Update an existing prompt. Only the fields provided in the request body will be updated.",
        "summary": "Update prompt",
        "tags": [
          "Prompt"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the prompt",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "prompt",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "User-defined labels for organizing and filtering prompts. Sets the complete list of tags, replacing any existing ones.",
                    "example": [
                      "product",
                      "high-priority"
                    ]
                  }
                },
                "required": [
                  "tags"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully updated prompt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromptResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "delete-prompt",
        "description": "Permanently delete one prompt and the AI answers collected for it. Use it when the prompt should no longer be tracked or kept; this cannot be undone. Turning monitoring off keeps the prompt and its history while stopping collection.",
        "summary": "Delete prompt",
        "tags": [
          "Prompt"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the prompt",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "prompt",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Successfully deleted prompt"
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/prompts/{prompt}/toggle-monitoring": {
      "put": {
        "operationId": "update-prompt-monitoring",
        "description": "Changes the monitoring status for a prompt.\n\n\n> [!important]\n> Calling this endpoint uses **25 tokens** from your rate limit bucket. Learn more about rate limiting [here](#description/rate-limiting).\n",
        "summary": "Toggle prompt monitoring",
        "tags": [
          "Prompt"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the prompt",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "prompt",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromptToggleMonitoringBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully toggled prompt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromptResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "412": {
            "description": "Monitoring limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1009
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Monitoring limit exceeded"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/prompts/{prompt}/share-of-voice/aggregates": {
      "get": {
        "operationId": "get-prompt-share-of-voice-aggregates",
        "description": "Retrieve share of voice for the brands mentioned in one prompt's AI answers over a date range: the portion of all brand mentions each brand holds. Use it to compare brands within a single prompt.",
        "summary": "Get share of voice aggregates",
        "tags": [
          "Prompt Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the prompt",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "prompt",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter results by brand name",
              "example": "Acme Corporation"
            },
            "required": false,
            "name": "brandName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "rank",
                "share_of_voice",
                "mentions"
              ],
              "default": "rank",
              "description": "Field to sort results by",
              "example": "rank"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc",
              "description": "Direction to sort results",
              "example": "asc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShareOfVoiceAggregatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/prompts/{prompt}/share-of-voice/timeseries": {
      "get": {
        "operationId": "get-prompt-share-of-voice-timeseries",
        "description": "Retrieve prompt time series data showing share of voice evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range.",
        "summary": "Get share of voice time series",
        "tags": [
          "Prompt Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the prompt",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "prompt",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved time series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromptShareOfVoiceTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/prompts/{prompt}/visibility/aggregates": {
      "get": {
        "operationId": "get-prompt-visibility-aggregates",
        "description": "Retrieve visibility for the brands mentioned in one prompt's AI answers over a date range: the share of that prompt's answers mentioning each brand. Use it to see who appears in a single prompt.",
        "summary": "Get visibility aggregates",
        "tags": [
          "Prompt Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the prompt",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "prompt",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc",
              "description": "Direction to sort results",
              "example": "asc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter results by brand name",
              "example": "Acme Corporation"
            },
            "required": false,
            "name": "brandName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "rank",
                "visibility"
              ],
              "default": "rank",
              "description": "Field to sort results by",
              "example": "rank"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VisibilityAggregatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/prompts/{prompt}/visibility/timeseries": {
      "get": {
        "operationId": "get-prompt-visibility-timeseries",
        "description": "Retrieve prompt time series data showing visibility evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range.",
        "summary": "Get visibility time series",
        "tags": [
          "Prompt Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the prompt",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "prompt",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved time series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromptVisibilityTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/prompts/{prompt}/citations/aggregates": {
      "get": {
        "operationId": "get-prompt-citations-aggregates",
        "description": "Retrieve the web sources cited by one prompt's AI answers over a date range, with how often each source is cited. Use it to find which pages AI engines draw on for that prompt.",
        "summary": "Get citations aggregates",
        "tags": [
          "Prompt Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the prompt",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "prompt",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc",
              "description": "Direction to sort results",
              "example": "desc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter by source domain name",
              "example": "example.com"
            },
            "required": false,
            "name": "sourceName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "owned",
                "third_party",
                "social"
              ],
              "description": "Filter by citation ownership type",
              "example": "owned"
            },
            "required": false,
            "name": "sourceType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "total_citations"
              ],
              "default": "total_citations",
              "description": "Field to sort results by",
              "example": "total_citations"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CitationsAggregatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/prompts/{prompt}/citations/timeseries": {
      "get": {
        "operationId": "get-prompt-citations-timeseries",
        "description": "Retrieve prompt time series data showing citations evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range.",
        "summary": "Get citations time series",
        "tags": [
          "Prompt Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the prompt",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "prompt",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved time series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromptCitationsTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/prompts/{prompt}/sentiment/timeseries": {
      "get": {
        "operationId": "get-prompt-sentiment-timeseries",
        "description": "Retrieve daily sentiment distribution over time for the owned brand within a prompt (competitors are not included). Returns counts of endorsed, undermined, and neutral feature mentions per day within the specified date range.",
        "summary": "Get sentiment time series",
        "tags": [
          "Prompt Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the prompt",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "prompt",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved sentiment time series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromptSentimentTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/prompts/{prompt}/sentiment/aggregates": {
      "get": {
        "operationId": "get-prompt-sentiment-aggregates",
        "description": "Retrieve a flat, paginated list of sentiment aggregates for a prompt. Each row represents a unique brand-feature pair with counts of endorsed, undermined, and neutral feature mentions.",
        "summary": "Get sentiment aggregates",
        "tags": [
          "Prompt Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the prompt",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "prompt",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter results by brand name",
              "example": "Acme Corporation"
            },
            "required": false,
            "name": "brandName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter results by feature name",
              "example": "customer support"
            },
            "required": false,
            "name": "featureName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "rank",
                "total_mentions",
                "endorsed_mentions",
                "undermined_mentions",
                "neutral_mentions"
              ],
              "default": "rank",
              "description": "Field to sort results by",
              "example": "rank"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc",
              "description": "Direction to sort results",
              "example": "asc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved sentiment aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SentimentAggregatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands/{brand}/topics": {
      "get": {
        "deprecated": true,
        "operationId": "list-brand-topics",
        "description": "Retrieve a paginated list of topics.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/prompts` instead. It returns all prompts for the brand and supports `type`, `countries`, and `tags` filters to narrow the results.",
        "summary": "List topics",
        "tags": [
          "Topic"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for sorting data (ISO 8601 date format). Defaults to 7 days ago. Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": false,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for sorting data (ISO 8601 date format). Defaults to today. Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": false,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of ISO 3166-1 alpha-2 country codes to filter topics",
              "example": "us,gb,de"
            },
            "required": false,
            "name": "countries",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter topics by AI engine. If empty, returns topics for all AI engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "name",
                "share_of_voice",
                "updated_at",
                "country"
              ],
              "default": "updated_at",
              "description": "Field to sort results by",
              "example": "updated_at"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc",
              "description": "Direction to sort results",
              "example": "desc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "suggested",
                "imported",
                "custom",
                "active",
                "paused"
              ],
              "description": "Filter topics by monitoring status",
              "example": "active"
            },
            "required": false,
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "nullable": true,
              "description": "Comma-separated list of tags to filter topics",
              "example": "product,high-priority"
            },
            "required": false,
            "name": "tags",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "any"
              ],
              "description": "How to match tags: 'any' returns topics with at least one selected tag (OR), 'all' returns topics with every selected tag (AND). Defaults to 'any'.",
              "example": "any"
            },
            "required": false,
            "name": "tagsMatchMode",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ],
              "description": "Filter by topic type",
              "example": "Non-Branded"
            },
            "required": false,
            "name": "type",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved topics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopicsListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "deprecated": true,
        "operationId": "create-brand-topic",
        "description": "Creates a new non-monitored topic with associated prompts. If a topic with the same name and location already exists for this brand, the prompts will be added to the existing topic instead.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `POST /api/v1/brands/{brand}/prompts` instead.",
        "summary": "Create topic",
        "tags": [
          "Topic"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTopicBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created topic",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateTopicResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/topics/import": {
      "post": {
        "deprecated": true,
        "operationId": "import-topics",
        "description": "Bulk-import prompts from parsed CSV rows. Rows missing a topic are grouped via automatic topic discovery. Returns a report detailing created topics, skipped duplicates, and row-level errors.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `POST /api/v1/brands/{brand}/prompts` instead.",
        "summary": "Bulk import prompts",
        "tags": [
          "Topic"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImportRequestBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully executed bulk import",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImportResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/topics/{topic}": {
      "get": {
        "deprecated": true,
        "operationId": "get-topic",
        "description": "Retrieve a topic by its id.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/prompts` instead. It returns all prompts for the brand and supports `type`, `countries`, and `tags` filters to narrow the results.",
        "summary": "Get topic",
        "tags": [
          "Topic"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the topic",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "topic",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved topic",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopicResponse"
                },
                "example": {
                  "data": {
                    "createdAt": "2026-01-01T09:30:00Z",
                    "id": "550e8400-e29b-41d4-a716-446655440000",
                    "location": "us",
                    "name": "best software",
                    "status": "active",
                    "tags": [
                      "product",
                      "high-priority"
                    ],
                    "topicSource": "custom",
                    "topicType": "Non-Branded"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "patch": {
        "deprecated": true,
        "operationId": "update-topic",
        "description": "Update an existing topic. Only the fields provided in the request body will be updated.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `PATCH /api/v1/prompts/{prompt}` to update individual prompts instead.",
        "summary": "Update topic",
        "tags": [
          "Topic"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the topic",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "topic",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "User-defined labels for organizing and filtering topics. Sets the complete list of tags, replacing any existing ones.",
                    "example": [
                      "product",
                      "high-priority"
                    ]
                  }
                },
                "required": [
                  "tags"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully updated topic",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopicResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "delete": {
        "deprecated": true,
        "operationId": "delete-topic",
        "description": "Delete a topic and all its associated data including prompts. This action cannot be undone.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `DELETE /api/v1/prompts/{prompt}` to delete individual prompts instead.",
        "summary": "Delete topic",
        "tags": [
          "Topic"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the topic",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "topic",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Successfully deleted topic"
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/topics/{topic}/toggle-monitoring": {
      "put": {
        "deprecated": true,
        "operationId": "update-topic-monitoring",
        "description": "Changes the monitoring status for a topic and all its prompts.\n\n\n> [!important]\n> Calling this endpoint uses **25 tokens** from your rate limit bucket. Learn more about rate limiting [here](#description/rate-limiting).\n\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `PUT /api/v1/prompts/{prompt}/toggle-monitoring` to toggle monitoring for individual prompts instead.",
        "summary": "Toggle topic monitoring",
        "tags": [
          "Topic"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the topic",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "topic",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TopicToggleMonitoringBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully toggled topic",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopicResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "412": {
            "description": "Monitoring limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1009
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Monitoring limit exceeded"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/topics/{topic}/share-of-voice/aggregates": {
      "get": {
        "deprecated": true,
        "operationId": "get-topic-share-of-voice-aggregates",
        "description": "Retrieve a paginated list of topic share of voice aggregates.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/share-of-voice/aggregates` with the `promptType` query parameter for a Branded/Non-Branded split, or create a View (`POST /api/v1/brands/{brand}/views`) to replicate this topic's specific prompt grouping and query `GET /api/v1/views/{view}/share-of-voice/aggregates` instead.",
        "summary": "Get share of voice aggregates",
        "tags": [
          "Topic Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the topic",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "topic",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter results by brand name",
              "example": "Acme Corporation"
            },
            "required": false,
            "name": "brandName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "rank",
                "share_of_voice",
                "mentions"
              ],
              "default": "rank",
              "description": "Field to sort results by",
              "example": "rank"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc",
              "description": "Direction to sort results",
              "example": "asc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShareOfVoiceAggregatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/topics/{topic}/share-of-voice/timeseries": {
      "get": {
        "deprecated": true,
        "operationId": "get-topic-share-of-voice-timeseries",
        "description": "Retrieve topic time series data showing share of voice evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/share-of-voice/timeseries` with the `promptType` query parameter for a Branded/Non-Branded split, or create a View (`POST /api/v1/brands/{brand}/views`) to replicate this topic's specific prompt grouping and query `GET /api/v1/views/{view}/share-of-voice/timeseries` instead.",
        "summary": "Get share of voice time series",
        "tags": [
          "Topic Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the topic",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "topic",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved time series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopicShareOfVoiceTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/topics/{topic}/visibility/aggregates": {
      "get": {
        "deprecated": true,
        "operationId": "get-topic-visibility-aggregates",
        "description": "Retrieve a paginated list of topic visibility aggregates.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/visibility/aggregates` with the `promptType` query parameter for a Branded/Non-Branded split, or create a View (`POST /api/v1/brands/{brand}/views`) to replicate this topic's specific prompt grouping and query `GET /api/v1/views/{view}/visibility/aggregates` instead.",
        "summary": "Get visibility aggregates",
        "tags": [
          "Topic Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the topic",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "topic",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc",
              "description": "Direction to sort results",
              "example": "asc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter results by brand name",
              "example": "Acme Corporation"
            },
            "required": false,
            "name": "brandName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "rank",
                "visibility"
              ],
              "default": "rank",
              "description": "Field to sort results by",
              "example": "rank"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VisibilityAggregatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/topics/{topic}/visibility/timeseries": {
      "get": {
        "deprecated": true,
        "operationId": "get-topic-visibility-timeseries",
        "description": "Retrieve topic time series data showing visibility evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/visibility/timeseries` with the `promptType` query parameter for a Branded/Non-Branded split, or create a View (`POST /api/v1/brands/{brand}/views`) to replicate this topic's specific prompt grouping and query `GET /api/v1/views/{view}/visibility/timeseries` instead.",
        "summary": "Get visibility time series",
        "tags": [
          "Topic Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the topic",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "topic",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved time series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopicVisibilityTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/topics/{topic}/citations/aggregates": {
      "get": {
        "deprecated": true,
        "operationId": "get-topic-citations-aggregates",
        "description": "Retrieve a paginated list of topic citations aggregates.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/citations/aggregates` with the `promptType` query parameter for a Branded/Non-Branded split, or create a View (`POST /api/v1/brands/{brand}/views`) to replicate this topic's specific prompt grouping and query `GET /api/v1/views/{view}/citations/aggregates` instead.",
        "summary": "Get citations aggregates",
        "tags": [
          "Topic Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the topic",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "topic",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc",
              "description": "Direction to sort results",
              "example": "desc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter by source domain name",
              "example": "example.com"
            },
            "required": false,
            "name": "sourceName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "owned",
                "third_party",
                "social"
              ],
              "description": "Filter by citation ownership type",
              "example": "owned"
            },
            "required": false,
            "name": "sourceType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "total_citations"
              ],
              "default": "total_citations",
              "description": "Field to sort results by",
              "example": "total_citations"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CitationsAggregatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/topics/{topic}/citations/timeseries": {
      "get": {
        "deprecated": true,
        "operationId": "get-topic-citations-timeseries",
        "description": "Retrieve topic time series data showing citations evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/citations/timeseries` with the `promptType` query parameter for a Branded/Non-Branded split, or create a View (`POST /api/v1/brands/{brand}/views`) to replicate this topic's specific prompt grouping and query `GET /api/v1/views/{view}/citations/timeseries` instead.",
        "summary": "Get citations time series",
        "tags": [
          "Topic Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the topic",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "topic",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved time series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopicCitationsTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/topics/{topic}/sentiment/timeseries": {
      "get": {
        "deprecated": true,
        "operationId": "get-topic-sentiment-timeseries",
        "description": "Retrieve daily sentiment distribution over time for the owned brand within a topic (competitors are not included). Returns counts of endorsed, undermined, and neutral feature mentions per day within the specified date range.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/sentiment/timeseries` with the `promptType` query parameter for a Branded/Non-Branded split, or create a View (`POST /api/v1/brands/{brand}/views`) to replicate this topic's specific prompt grouping and query `GET /api/v1/views/{view}/sentiment/timeseries` instead.",
        "summary": "Get sentiment time series",
        "tags": [
          "Topic Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the topic",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "topic",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved sentiment time series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopicSentimentTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/topics/{topic}/sentiment/aggregates": {
      "get": {
        "deprecated": true,
        "operationId": "get-topic-sentiment-aggregates",
        "description": "Retrieve a flat, paginated list of sentiment aggregates for a topic. Each row represents a unique brand-feature pair with counts of endorsed, undermined, and neutral feature mentions.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/sentiment/aggregates` with the `promptType` query parameter for a Branded/Non-Branded split, or create a View (`POST /api/v1/brands/{brand}/views`) to replicate this topic's specific prompt grouping and query `GET /api/v1/views/{view}/sentiment/aggregates` instead.",
        "summary": "Get sentiment aggregates",
        "tags": [
          "Topic Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the topic",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "topic",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter results by brand name",
              "example": "Acme Corporation"
            },
            "required": false,
            "name": "brandName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter results by feature name",
              "example": "customer support"
            },
            "required": false,
            "name": "featureName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "rank",
                "total_mentions",
                "endorsed_mentions",
                "undermined_mentions",
                "neutral_mentions"
              ],
              "default": "rank",
              "description": "Field to sort results by",
              "example": "rank"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc",
              "description": "Direction to sort results",
              "example": "asc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved sentiment aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SentimentAggregatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands/{brand}/trends": {
      "get": {
        "deprecated": true,
        "operationId": "list-brand-trends",
        "description": "Retrieve a paginated list of trends.\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation. No direct replacement — use `GET /api/v1/brands/{brand}/prompts` to list all prompts for a brand instead. It supports `type`, `countries`, and `tags` filters to narrow the results.",
        "summary": "List trends",
        "tags": [
          "Trend"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated list of ISO 3166-1 alpha-2 country codes to filter trends",
              "example": "us,gb,de"
            },
            "required": false,
            "name": "locations",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Search for trends with this name"
            },
            "required": false,
            "name": "name",
            "in": "query"
          },
          {
            "schema": {
              "type": "boolean",
              "nullable": true,
              "description": "Filter by only new trends"
            },
            "required": false,
            "name": "unacceptedOnly",
            "in": "query"
          },
          {
            "schema": {
              "type": "boolean",
              "nullable": true,
              "description": "Filter by only new trends (created after last visit)"
            },
            "required": false,
            "name": "newOnly",
            "in": "query"
          },
          {
            "schema": {
              "type": "number",
              "nullable": true,
              "default": 6,
              "description": "Number of data points to retrieve"
            },
            "required": false,
            "name": "numberOfPoints",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "LOW",
                "MEDIUM",
                "HIGH"
              ]
            },
            "required": false,
            "name": "relativeDifficulty",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "suggested",
                "imported",
                "custom",
                "active",
                "paused"
              ]
            },
            "required": false,
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "Branded",
                "Non-Branded"
              ]
            },
            "required": false,
            "name": "topicType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "topic",
                "searchVolume",
                "relativeDifficulty"
              ],
              "default": "searchVolume"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved trends",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrendsListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "deprecated": true,
        "operationId": "create-brand-trends",
        "description": "Creates new trends from a list of imported keywords. This method is asynchronous and it requires querying for new trends to see when the import finishes.\n\n\n> [!important]\n> Calling this endpoint uses **25 tokens** from your rate limit bucket. Learn more about rate limiting [here](#description/rate-limiting).\n\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `POST /api/v1/brands/{brand}/prompts` to create prompts directly instead.",
        "summary": "Import trends",
        "tags": [
          "Trend"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "country": {
                    "type": "string",
                    "minLength": 2,
                    "description": "ISO 3166-1 alpha-2 country code for the topic's target market",
                    "example": "us"
                  },
                  "keywords": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1000,
                    "description": "A list of comma-separated keywords to import and use as trends",
                    "example": "software,tooling,tech"
                  }
                },
                "required": [
                  "country",
                  "keywords"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully imported trends",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrendsImportResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/trends/{trend}/accept": {
      "post": {
        "deprecated": true,
        "operationId": "accept-trend",
        "description": "Accepts a trend and starts monitoring all the selected prompt ids. This converts the trend into an active topic that can be managed via the topics endpoints.\n\n\n> [!important]\n> Calling this endpoint uses **25 tokens** from your rate limit bucket. Learn more about rate limiting [here](#description/rate-limiting).\n\n\n**Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `POST /api/v1/brands/{brand}/prompts` to create and start monitoring prompts directly instead.",
        "summary": "Accept trend",
        "tags": [
          "Trend"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the trend",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "trend",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrendStartMonitoringBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully accepts a trend",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrendStartMonitoringResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "412": {
            "description": "Monitoring limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1009
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Monitoring limit exceeded"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands/{brand}/views": {
      "get": {
        "operationId": "list-brand-views",
        "description": "Retrieve a paginated list of the brand's views.\n\nA view is a named saved filter over a brand's prompts (any combination of prompt type, countries, tags, and status). The prompt set is resolved from the filters at query time, so a view always reflects the brand's current prompts.",
        "summary": "List views",
        "tags": [
          "View"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved views",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ViewsListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "create-brand-view",
        "description": "Create a view for a brand. The view name must be unique per brand (case-insensitive). Omit `filters` (or pass `{}`) for a view matching all of the brand's prompts.\n\nA view is a named saved filter over a brand's prompts (any combination of prompt type, countries, tags, and status). The prompt set is resolved from the filters at query time, so a view always reflects the brand's current prompts.",
        "summary": "Create view",
        "tags": [
          "View"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the brand",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "brand",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateViewBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created view",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ViewResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Duplicated item",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1008
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Duplicated item"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/views/{view}": {
      "get": {
        "operationId": "get-view",
        "description": "Retrieve a view by its id.\n\nA view is a named saved filter over a brand's prompts (any combination of prompt type, countries, tags, and status). The prompt set is resolved from the filters at query time, so a view always reflects the brand's current prompts.",
        "summary": "Get view",
        "tags": [
          "View"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the view",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "view",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved view",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ViewResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "update-view",
        "description": "Update a view's name and/or filters. `filters` replaces the entire filters object — include every criterion the view should keep.",
        "summary": "Update view",
        "tags": [
          "View"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the view",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "view",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PatchViewBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully updated view",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ViewResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Duplicated item",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1008
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Duplicated item"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "delete-view",
        "description": "Delete a view. Only the saved filter is removed — the prompts it groups are not affected.",
        "summary": "Delete view",
        "tags": [
          "View"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the view",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "view",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Successfully deleted view"
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/views/{view}/prompts": {
      "get": {
        "operationId": "list-view-prompts",
        "description": "Retrieve the paginated list of prompts the view currently groups, with summary performance metrics per prompt. The prompt set is resolved from the view's saved filters at query time.",
        "summary": "List view prompts",
        "tags": [
          "View"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the view",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "view",
            "in": "path"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for sorting data (ISO 8601 date format). Defaults to 7 days ago. Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": false,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for sorting data (ISO 8601 date format). Defaults to today. Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": false,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter results by specific AI engine. Omit to return prompts for all supported engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "name",
                "share_of_voice",
                "net_sentiment",
                "updated_at",
                "country"
              ],
              "default": "updated_at",
              "description": "Field to sort prompts by",
              "example": "updated_at"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc",
              "description": "Sort order direction",
              "example": "desc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved prompts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandPromptsListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/views/{view}/visibility/aggregates": {
      "get": {
        "operationId": "get-view-visibility-aggregates",
        "description": "Retrieve a paginated list of visibility aggregates over the prompts the view groups. The prompt set comes from the view's saved filters; the query parameters only control dates, engine, sorting, and pagination.",
        "summary": "Get visibility aggregates",
        "tags": [
          "View Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the view",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "view",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc",
              "description": "Direction to sort results",
              "example": "asc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter results by brand name",
              "example": "Acme Corporation"
            },
            "required": false,
            "name": "brandName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "rank",
                "visibility"
              ],
              "default": "rank",
              "description": "Field to sort results by",
              "example": "rank"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VisibilityAggregatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/views/{view}/visibility/timeseries": {
      "get": {
        "operationId": "get-view-visibility-timeseries",
        "description": "Retrieve visibility time series over the prompts the view groups. The prompt set comes from the view's saved filters; the query parameters only control dates and engine.",
        "summary": "Get visibility time series",
        "tags": [
          "View Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the view",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "view",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved time series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ViewVisibilityTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/views/{view}/share-of-voice/aggregates": {
      "get": {
        "operationId": "get-view-share-of-voice-aggregates",
        "description": "Retrieve a paginated list of share of voice aggregates over the prompts the view groups. The prompt set comes from the view's saved filters; the query parameters only control dates, engine, sorting, and pagination.",
        "summary": "Get share of voice aggregates",
        "tags": [
          "View Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the view",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "view",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter results by brand name",
              "example": "Acme Corporation"
            },
            "required": false,
            "name": "brandName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "rank",
                "share_of_voice",
                "mentions"
              ],
              "default": "rank",
              "description": "Field to sort results by",
              "example": "rank"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc",
              "description": "Direction to sort results",
              "example": "asc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShareOfVoiceAggregatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/views/{view}/share-of-voice/timeseries": {
      "get": {
        "operationId": "get-view-share-of-voice-timeseries",
        "description": "Retrieve share of voice time series over the prompts the view groups. The prompt set comes from the view's saved filters; the query parameters only control dates and engine.",
        "summary": "Get share of voice time series",
        "tags": [
          "View Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the view",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "view",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved time series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ViewShareOfVoiceTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/views/{view}/citations/aggregates": {
      "get": {
        "operationId": "get-view-citations-aggregates",
        "description": "Retrieve a paginated list of citation aggregates over the prompts the view groups. The prompt set comes from the view's saved filters; the query parameters only control dates, engine, sorting, filtering by source, and pagination.",
        "summary": "Get citation aggregates",
        "tags": [
          "View Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the view",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "view",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc",
              "description": "Direction to sort results",
              "example": "desc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter by source domain name",
              "example": "example.com"
            },
            "required": false,
            "name": "sourceName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "owned",
                "third_party",
                "social"
              ],
              "description": "Filter by citation ownership type",
              "example": "owned"
            },
            "required": false,
            "name": "sourceType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "total_citations"
              ],
              "default": "total_citations",
              "description": "Field to sort results by",
              "example": "total_citations"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CitationsAggregatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/views/{view}/citations/timeseries": {
      "get": {
        "operationId": "get-view-citations-timeseries",
        "description": "Retrieve citations time series over the prompts the view groups. The prompt set comes from the view's saved filters; the query parameters only control dates and engine.",
        "summary": "Get citations time series",
        "tags": [
          "View Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the view",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "view",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved time series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ViewCitationsTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/views/{view}/sentiment/aggregates": {
      "get": {
        "operationId": "get-view-sentiment-aggregates",
        "description": "Retrieve a paginated list of sentiment aggregates (one row per brand-feature pair) over the prompts the view groups. The prompt set comes from the view's saved filters; the query parameters only control dates, engine, sorting, filtering by brand or feature, and pagination.",
        "summary": "Get sentiment aggregates",
        "tags": [
          "View Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the view",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "view",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (1-indexed)",
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 5,
              "maximum": 100,
              "default": 20,
              "description": "Number of items per page",
              "example": 10
            },
            "required": false,
            "name": "pageSize",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter results by brand name",
              "example": "Acme Corporation"
            },
            "required": false,
            "name": "brandName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter results by feature name",
              "example": "customer support"
            },
            "required": false,
            "name": "featureName",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "rank",
                "total_mentions",
                "endorsed_mentions",
                "undermined_mentions",
                "neutral_mentions"
              ],
              "default": "rank",
              "description": "Field to sort results by",
              "example": "rank"
            },
            "required": false,
            "name": "sortBy",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc",
              "description": "Direction to sort results",
              "example": "asc"
            },
            "required": false,
            "name": "sortDirection",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SentimentAggregatesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/views/{view}/sentiment/timeseries": {
      "get": {
        "operationId": "get-view-sentiment-timeseries",
        "description": "Retrieve daily sentiment feature mention distribution over the prompts the view groups. The prompt set comes from the view's saved filters; the query parameters only control dates and engine.",
        "summary": "Get sentiment time series",
        "tags": [
          "View Performance"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for the view",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "name": "view",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Start date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-01"
            },
            "required": true,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "End date for filtering data (ISO 8601 date format). Range is inclusive.",
              "example": "2026-01-31"
            },
            "required": true,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "google-ai-overviews",
                "google-ai-mode",
                "perplexity",
                "openai",
                "gemini",
                "grok",
                "copilot",
                "claude"
              ],
              "description": "Filter by AI engine. If empty, returns results for all engines",
              "example": "openai"
            },
            "required": false,
            "name": "engine",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved time series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ViewSentimentTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1002
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid input parameters"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1004,
                            1005
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Invalid or expired API token",
                            "Missing authorization header. Please provide a Bearer token."
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1006
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Item not found"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            1001,
                            1003
                          ],
                          "description": "Numeric error code identifying the error type"
                        },
                        "description": {
                          "type": "string",
                          "enum": [
                            "Internal error",
                            "Authentication configuration error"
                          ],
                          "description": "Human-readable error message"
                        }
                      },
                      "required": [
                        "code",
                        "description"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}