{
  "openapi": "3.0.3",
  "info": {
    "title": "MentionBird.ai Visibility & LLM Tracker API",
    "description": "Track how a brand shows up in AI assistant answers. Read visibility metrics, share of voice, the domains AI platforms cite, per-prompt gaps, ranking advice and YouTube summaries \u2014 and add brands or prompts to track.",
    "version": "1.0.0",
    "contact": {
      "name": "MentionBird.ai Support",
      "url": "https://mentionbird.ai"
    }
  },
  "servers": [
    {
      "url": "https://api.mentionbird.ai/api/v1",
      "description": "MentionBird.ai REST API Server"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key (lmvz_live_...)",
        "description": "Bearer token authentication using your MentionBird.ai Account API key (starts with 'lmvz_live_')."
      }
    }
  },
  "paths": {
    "/brands/tracked": {
      "get": {
        "summary": "List Tracked Brands",
        "operationId": "listTrackedBrands",
        "description": "List every brand this workspace tracks. Call this first \u2014 other endpoints take the brand name exactly as returned here.",
        "responses": {
          "200": {
            "description": "List of tracked brands. domains lists the domains this workspace declared as the brand's own, each with include_subdomains; they are what the 'yours' ownership label matches, and an empty list means none are declared. domain is the first declared domain, else the brand's public domain, else null."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Discovery"
        ]
      },
      "post": {
        "summary": "Add Tracked Brand",
        "operationId": "addTrackedBrand",
        "description": "Start tracking a new brand. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Name of the brand to track."
                  },
                  "domain": {
                    "type": "string",
                    "description": "Primary domain, e.g. example.com. Registered as a brand-owned domain for this workspace only."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Brand is now tracked."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/queries": {
      "get": {
        "summary": "List Tracked Prompts",
        "operationId": "listQueries",
        "description": "List the prompts tracked for a brand, with their search-volume and difficulty buckets and the prompt ID token other endpoints need.",
        "responses": {
          "200": {
            "description": "Tracked prompts. llms lists the AI platforms each runs on, archived_llms the ones it was removed from, and archived is true when it runs on none."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          },
          {
            "name": "query_tag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter to one tag slug \u2014 see listQueryTags."
          },
          {
            "name": "include_archived",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Also list archived prompts."
          }
        ],
        "tags": [
          "Discovery"
        ]
      }
    },
    "/queries/tags": {
      "get": {
        "summary": "List Prompt Tags",
        "operationId": "listQueryTags",
        "description": "List the tags this workspace has assigned to a brand's prompts. Pass a tag's slug as `query_tag` on other endpoints.",
        "responses": {
          "200": {
            "description": "Prompt tags. prompt_count is how many of the brand's prompts carry the tag, archived ones included."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          }
        ],
        "tags": [
          "Discovery"
        ]
      },
      "post": {
        "summary": "Create a Tag",
        "operationId": "createTag",
        "description": "Create a prompt tag. When the brand already has a tag with the same slug, that tag comes back unchanged. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand",
                  "name"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  },
                  "name": {
                    "type": "string",
                    "description": "The tag's name, up to 100 characters."
                  },
                  "color": {
                    "type": "string",
                    "description": "Hex color, e.g. #0075ca. Optional."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The tag."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/llm-providers": {
      "get": {
        "summary": "List AI Platforms",
        "operationId": "listLLMProviders",
        "description": "List the AI platforms available to this workspace (ChatGPT, Claude, Gemini, Perplexity, Grok) and the models behind them.",
        "responses": {
          "200": {
            "description": "Available AI platforms."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Discovery"
        ]
      }
    },
    "/brands/competitors": {
      "get": {
        "summary": "List Competitors",
        "operationId": "listCompetitors",
        "description": "List the competitors tracked for a brand, with each one's domain. getTopMentionedBrands marks their rows is_tracked_competitor.",
        "responses": {
          "200": {
            "description": "Tracked competitors in name order. domains lists the domains this workspace declared for each, with include_subdomains; they are what the 'competitor:<name>' ownership label matches, and an empty list means none are declared. domain is the first declared domain, else the competitor's public domain, else null. A competitor gets a row in getTopMentionedBrands only when answers in the range named it, and not even then when every spelling of it falls inside the tracked brand's own spellings or an earlier-added competitor's: its mentions count under that row instead."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          }
        ],
        "tags": [
          "Discovery"
        ]
      },
      "post": {
        "summary": "Add Competitors",
        "operationId": "addCompetitors",
        "description": "Track competitors for a brand, up to the plan's per-brand limit (see getAccount). Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand",
                  "competitors"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  },
                  "competitors": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 255
                    },
                    "minItems": 1,
                    "maxItems": 50,
                    "description": "Competitor names. Allowed: 1\u201350 items, each up to 255 characters."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done. The body reports the outcome for each item."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/brands/aliases": {
      "get": {
        "summary": "List Brand Aliases",
        "operationId": "listAliases",
        "description": "List the extra spellings that count as the brand, or as one of its competitors, when an answer names them.",
        "responses": {
          "200": {
            "description": "Aliases, the brand's first. competitor is null for the brand's own. match_mode is exact (the whole name in an answer equals the alias, ignoring case) or contains (the name contains it)."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          }
        ],
        "tags": [
          "Discovery"
        ]
      },
      "post": {
        "summary": "Add Aliases",
        "operationId": "addAliases",
        "description": "Count extra spellings as the brand, or as a competitor, when an answer names them. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand",
                  "aliases"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  },
                  "aliases": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 255
                    },
                    "minItems": 1,
                    "maxItems": 50,
                    "description": "Spellings, e.g. 'acme shoes'. Allowed: 1\u201350 items, each up to 255 characters."
                  },
                  "match_mode": {
                    "type": "string",
                    "enum": [
                      "exact",
                      "contains"
                    ],
                    "default": "exact",
                    "description": "exact: the whole name in an answer equals the alias. contains: the name contains it."
                  },
                  "competitor": {
                    "type": "string",
                    "description": "A competitor's name, from listCompetitors, to act on that competitor. Omit it to act on the brand itself."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done. The body reports the outcome for each item."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/account": {
      "get": {
        "summary": "Get Plan and Usage",
        "operationId": "getAccount",
        "description": "Show the workspace's plan, credit balance, how much of each limit is used, the AI platforms the plan allows, and each paid agent's price. Call it before adding prompts, competitors or brands, or spending credits.",
        "responses": {
          "200": {
            "description": "Plan and usage. prompt_runs counts one prompt on one AI platform as one run, in one pool shared by every brand. allowed_providers are the slugs to pass as llms."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Discovery"
        ]
      }
    },
    "/visibility": {
      "get": {
        "summary": "Get Brand Visibility",
        "operationId": "getVisibility",
        "description": "How often the brand appears in AI answers, plus prominence score, average rank and sentiment. Group overall, by day, by platform or by tag.",
        "responses": {
          "200": {
            "description": "Visibility metrics. net_sentiment is -100..+100: how the AI platforms talk about the brand, not how often they name it. +100 = every labeled mention recommends it, -100 = every one criticizes it, 0 = balanced or uniformly neutral. It is computed over labeled mentions ONLY. sentiment_coverage_pct is what share of mentions carry a label; anything crawled before sentiment tracking began is unlabeled and counts toward neither side. Read the two together - net_sentiment 0 with coverage 0 means no data, not neutral, and must never be reported as neutral."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          },
          {
            "name": "group_by",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "overall",
              "enum": [
                "overall",
                "day",
                "provider",
                "query_tag"
              ]
            },
            "description": "Grouping granularity."
          },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO start date (YYYY-MM-DD). Defaults to 30 days ago. The range may span at most 365 days; a longer one is a 400."
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO end date (YYYY-MM-DD). Defaults to today."
          },
          {
            "name": "brand_prompt_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Limit to one prompt \u2014 token from listQueries."
          },
          {
            "name": "query_tag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter to one tag slug."
          },
          {
            "name": "llm_provider",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "openai",
                "claude",
                "gemini",
                "perplexity",
                "grok"
              ]
            },
            "description": "Filter to one AI platform."
          }
        ],
        "tags": [
          "Visibility"
        ]
      }
    },
    "/brands/top-mentioned": {
      "get": {
        "summary": "Get Share of Voice",
        "operationId": "getTopMentionedBrands",
        "description": "The brands named most often across this brand's tracked prompts \u2014 who you are losing to, and by how much.",
        "responses": {
          "200": {
            "description": "Brands ranked by mentions, each with its own sentiment so the brand can be compared with its competitors on tone as well as share of voice. net_sentiment is -100..+100: how the AI platforms talk about the brand, not how often they name it. +100 = every labeled mention recommends it, -100 = every one criticizes it, 0 = balanced or uniformly neutral. It is computed over labeled mentions ONLY. sentiment_coverage_pct is what share of mentions carry a label; anything crawled before sentiment tracking began is unlabeled and counts toward neither side. Read the two together - net_sentiment 0 with coverage 0 means no data, not neutral, and must never be reported as neutral."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO start date (YYYY-MM-DD). Defaults to 30 days ago. The range may span at most 365 days; a longer one is a 400."
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO end date (YYYY-MM-DD). Defaults to today."
          },
          {
            "name": "filter_by_brand",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Only answers that also mention this brand. The tracked brand's name or a competitor's name from listCompetitors matches every spelling of it; any other name matches that exact brand only. filters_applied.filter_by_brand_match says which."
          },
          {
            "name": "exclude_brand",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Only answers that do not mention this brand. The tracked brand's name or a competitor's name from listCompetitors matches every spelling of it; any other name matches that exact brand only. filters_applied.exclude_brand_match says which."
          },
          {
            "name": "brand_prompt_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Limit to one prompt \u2014 token from listQueries."
          },
          {
            "name": "query_tag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter to one tag slug."
          },
          {
            "name": "llm_provider",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "openai",
                "claude",
                "gemini",
                "perplexity",
                "grok"
              ]
            },
            "description": "Filter to one AI platform."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Rows per page. A value over the maximum reads as the maximum and sets filters_applied.limit_clamped. Allowed: 1\u2013100."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Rows to skip \u2014 the cursor for reading past `limit`. Default 0. While `has_more` is true, repeat with offset advanced by `returned_count`. Allowed: 0 or more."
          }
        ],
        "tags": [
          "Visibility"
        ]
      }
    },
    "/citations/domains": {
      "get": {
        "summary": "Get Top Cited Domains",
        "operationId": "getTopCitationDomains",
        "description": "The domains AI platforms cite most when answering this brand's prompts.",
        "responses": {
          "200": {
            "description": "Cited domains ranked by citation count - never by authority, and there is no authority sort or filter, so walk pages with offset before judging the best target. Each row's domain_authority is a 0-100 site-authority score. 0 is a real measured score meaning genuinely low authority; null is unknown - not yet looked up, or the lookup failed - so leave that row out of authority comparisons."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO start date (YYYY-MM-DD). Defaults to 30 days ago. The range may span at most 365 days; a longer one is a 400."
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO end date (YYYY-MM-DD). Defaults to today."
          },
          {
            "name": "filter_by_brand",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Only answers that also mention this brand. The tracked brand's name or a competitor's name from listCompetitors matches every spelling of it; any other name matches that exact brand only. filters_applied.filter_by_brand_match says which."
          },
          {
            "name": "exclude_brand",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Only answers that do not mention this brand. The tracked brand's name or a competitor's name from listCompetitors matches every spelling of it; any other name matches that exact brand only. filters_applied.exclude_brand_match says which."
          },
          {
            "name": "brand_prompt_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Limit to one prompt \u2014 token from listQueries."
          },
          {
            "name": "query_tag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter to one tag slug."
          },
          {
            "name": "llm_provider",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "openai",
                "claude",
                "gemini",
                "perplexity",
                "grok"
              ]
            },
            "description": "Filter to one AI platform."
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter to one domain."
          },
          {
            "name": "source_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Site category \u2014 see listCitationTags."
          },
          {
            "name": "content_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Page category \u2014 see listCitationTags."
          },
          {
            "name": "url_status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "unknown",
                "alive",
                "dead",
                "redirect"
              ]
            },
            "description": "Link health filter."
          },
          {
            "name": "ownership",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by who owns the domain: 'yours', 'earned', 'competitor', or 'competitor:<name>' with a name from listCompetitors."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Substring match on domain, URL or page title."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Rows per page. A value over the maximum reads as the maximum and sets filters_applied.limit_clamped. Allowed: 1\u2013100."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Rows to skip \u2014 the cursor for reading past `limit`. Default 0. While `has_more` is true, repeat with offset advanced by `returned_count`. Allowed: 0 or more."
          }
        ],
        "tags": [
          "Citations"
        ]
      }
    },
    "/citations": {
      "get": {
        "summary": "List Citations",
        "operationId": "listCitations",
        "description": "Individual cited URLs with page metadata, for detailed source analysis.",
        "responses": {
          "200": {
            "description": "Citations with page metadata. Each row's domain_authority is a 0-100 site-authority score for the row's domain, not the page. 0 is a real measured score meaning genuinely low authority; null is unknown - not yet looked up, or the lookup failed - so leave that row out of authority comparisons."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO start date (YYYY-MM-DD). Defaults to 30 days ago. The range may span at most 365 days; a longer one is a 400."
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO end date (YYYY-MM-DD). Defaults to today."
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter to one domain."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Substring match on domain, URL or page title."
          },
          {
            "name": "source_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Site category \u2014 see listCitationTags."
          },
          {
            "name": "content_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Page category \u2014 see listCitationTags."
          },
          {
            "name": "url_status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "unknown",
                "alive",
                "dead",
                "redirect"
              ]
            },
            "description": "Link health filter."
          },
          {
            "name": "brand_prompt_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Limit to one prompt \u2014 token from listQueries."
          },
          {
            "name": "query_tag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter to one tag slug."
          },
          {
            "name": "llm_provider",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "openai",
                "claude",
                "gemini",
                "perplexity",
                "grok"
              ]
            },
            "description": "Filter to one AI platform."
          },
          {
            "name": "include_extras",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Include per-domain extracted metadata."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Rows per page. A value over the maximum reads as the maximum and sets filters_applied.limit_clamped. Allowed: 1\u2013100."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Rows to skip \u2014 the cursor for reading past `limit`. Default 0. While `has_more` is true, repeat with offset advanced by `returned_count`. Allowed: 0 or more."
          }
        ],
        "tags": [
          "Citations"
        ]
      }
    },
    "/citations/tags": {
      "get": {
        "summary": "List Citation Taxonomy",
        "operationId": "listCitationTags",
        "description": "The valid source_type and content_type values to pass to the citation endpoints. source_type describes the kind of site, content_type the kind of page.",
        "responses": {
          "200": {
            "description": "Citation taxonomy."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Citations"
        ]
      }
    },
    "/citations/breakdown": {
      "get": {
        "summary": "Get Citation Breakdown",
        "operationId": "getCitationBreakdown",
        "description": "The kinds of sources AI platforms cite when answering this brand's prompts: those citations grouped by source_type (kind of site), content_type (kind of page) or url_status (link health).",
        "responses": {
          "200": {
            "description": "Groups ranked by citation_count, each with share_pct of the counts summed over every group. Under source_type and content_type, citations not yet tagged on that dimension are left out of both; under url_status, a link not yet checked counts as unknown. A citation tagged with several page categories counts once under each of them. The domain, source_type, content_type and url_status filters narrow the citations before grouping, and each citation still counts under every category it carries: content_type=listicle with dimension=content_type also returns the other page categories those listicles are tagged with."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO start date (YYYY-MM-DD). Defaults to 30 days ago. The range may span at most 365 days; a longer one is a 400."
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO end date (YYYY-MM-DD). Defaults to today."
          },
          {
            "name": "dimension",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "source_type",
              "enum": [
                "source_type",
                "content_type",
                "url_status"
              ]
            },
            "description": "What to group the citations by."
          },
          {
            "name": "brand_prompt_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Limit to one prompt \u2014 token from listQueries."
          },
          {
            "name": "query_tag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter to one tag slug."
          },
          {
            "name": "llm_provider",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "openai",
                "claude",
                "gemini",
                "perplexity",
                "grok"
              ]
            },
            "description": "Filter to one AI platform."
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter to one domain."
          },
          {
            "name": "source_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Site category \u2014 see listCitationTags."
          },
          {
            "name": "content_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Page category \u2014 see listCitationTags."
          },
          {
            "name": "url_status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "unknown",
                "alive",
                "dead",
                "redirect"
              ]
            },
            "description": "Link health filter."
          }
        ],
        "tags": [
          "Citations"
        ]
      }
    },
    "/sources/owned-share": {
      "get": {
        "summary": "Get Owned vs Earned Share",
        "operationId": "getOwnedSourceShare",
        "description": "How citations split between domains the brand owns, competitor-owned domains and earned third-party coverage. The filters narrow it the way the dashboard's sources page does.",
        "responses": {
          "200": {
            "description": "Ownership breakdown."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO start date (YYYY-MM-DD). Defaults to 30 days ago. The range may span at most 365 days; a longer one is a 400."
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO end date (YYYY-MM-DD). Defaults to today."
          },
          {
            "name": "llm_provider",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "openai",
                "claude",
                "gemini",
                "perplexity",
                "grok"
              ]
            },
            "description": "Filter to one AI platform."
          },
          {
            "name": "query_tag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter to one tag slug."
          },
          {
            "name": "brand_prompt_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Limit to one prompt \u2014 token from listQueries."
          },
          {
            "name": "source_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Site category \u2014 see listCitationTags."
          },
          {
            "name": "content_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Page category \u2014 see listCitationTags."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Substring match on domain, URL or page title."
          }
        ],
        "tags": [
          "Citations"
        ]
      }
    },
    "/searches": {
      "get": {
        "summary": "Get Top Web Searches",
        "operationId": "getTopWebSearches",
        "description": "The searches AI models ran before answering this brand's prompts - the terms to rank for, as opposed to the pages already cited.",
        "responses": {
          "200": {
            "description": "Searches ranked by how often they were run. Read the coverage block before quoting any rate: a provider with exposes_searches false does not publish its searches, so its answers are absent rather than zero. no_search_rate_pct is the share of readable answers where the model searched nothing and replied from prior knowledge - it is computed over runs_with_readable_searches, never over runs, and is null when nothing was readable. Search rankings cannot reach the prompts in that share. In topic mode rows come back pre-order - a topic, then its sub-topics - with depth, topic_id and parent_topic_id for rebuilding the nesting. In topic mode the search field is a synthesized label naming what the topic is about, not a quotation: it will not appear verbatim under group_by=search, and must not be fed back as the q filter or re-run as a search string. occurrences on a topic INCLUDES its sub-topics, so those numbers do not sum to total_occurrences; direct_occurrences is the row's own share and those do sum exactly. The last row is Other searches, the terminal bucket for searches too rare to have been mined into a topic and the one label that names no subject; unmatched_terms / unmatched_pct_of_searches report its size, which is a large share of volume - the visible rows are not the whole picture. topics_ready false means the brand's tree has not been mined yet and rows are one topic per search term. total_occurrences and total_unique_searches are identical in both modes and neither is the pagination total - walk on total_count, which counts topic rows here and search strings under group_by=search. Every one of these counts is zero for a provider with exposes_searches false because there is nothing to count, which is not the same as the model having searched nothing. language names the tree these rows came from and available_languages every tree the brand has; for a multi-language brand these rows are one language's slice, not the brand's whole volume. Each row carries searches_by_provider, a provider code to count map summing to occurrences, and the response carries searches_by_provider_total, the same map over every row in scope. Do NOT read a row's raw percentages as a model preference: they conflate how many runs were bought on each model with how much each model searches per run, which on real data turned a 1.7x preference into an apparent 15x one. Divide by searches_by_provider_total to get the topic's share of that provider's own searching, which cancels both. A provider that publishes nothing is absent from both maps rather than present at zero, so a missing key means unknown, not zero searches. searches_by_provider_total is row-level and so is narrowed by search, unlike coverage.by_provider[*].searches which reads the pre-filter run set; with no filters applied the two agree. Every row carries first_seen_in_range, the earliest run WITHIN the requested window rather than the first time the term was ever searched - on a 30-day read every value is bounded below by start_date, so a term the brand has triggered for a year reads as new; widen the window to push the bound back, there is no never-seen-before flag. Under group_by=search each row also carries triggered_by: the prompt that produced that search most often, as brand_prompt_id (the same opaque token listQueries returns, passable straight back as the brand_prompt_id filter), prompt and other_prompts. It names one prompt rather than listing them because 94.6% of terms come from exactly one, and is null only when that prompt has since been removed. Topic rows carry prompt_count instead, for the same reason depth and topic_id appear only on topics: a topic spans several prompts, so naming one would be a lie of omission."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO start date (YYYY-MM-DD). Defaults to 30 days ago. The range may span at most 365 days; a longer one is a 400."
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO end date (YYYY-MM-DD). Defaults to today."
          },
          {
            "name": "brand_prompt_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Limit to one prompt \u2014 token from listQueries."
          },
          {
            "name": "query_tag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter to one tag slug."
          },
          {
            "name": "llm_provider",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "openai",
                "claude",
                "gemini",
                "perplexity",
                "grok"
              ]
            },
            "description": "Filter to one AI platform."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Substring match on the search text. Narrows the rows and total_occurrences; everything under coverage is run-level and stays put. Applied before grouping, so under a filter a topic's counts describe only its matching phrasings, and its label may re-spell or re-order to match them. Topic identity is mined nightly and does not move with the filter; the label's word set follows that identity, only its wording follows the filter."
          },
          {
            "name": "group_by",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "topic",
              "enum": [
                "topic",
                "search"
              ]
            },
            "description": "topic (default) returns the nightly-mined topic hierarchy flattened pre-order, each row carrying depth, topic_id and parent_topic_id; search returns one flat row per exact search string. Anything else is a 400, not a silent fallback - this selects which rows you get. Must match search_queries.VALID_GROUP_BY exactly. The older spelling theme is still accepted for topic and is deliberately not listed here, so nothing new depends on it."
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO 639-1 code selecting WHICH of the brand's topic trees to read. A brand running prompts in several languages has one tree per language, mined with that language's stemmer, so they cannot be merged and there is no all-languages view: this narrows the rows as well as the grouping. Omit for the brand's largest language. Not an enum and not a 400 - which languages exist is per-brand, so an unknown code falls back to that default and the response's language field says which was used. available_languages lists every one with its own search count; those counts sum to the brand's whole volume, so nothing is hidden by there being no combined view. An empty string means the searches are not stemmed - what an untagged or unsupported language gets; pass und to select that bucket, since its code is the empty string and an empty query parameter reads as an absent one. An unrecognised code names nothing and falls back to the default rather than landing on the unstemmed bucket. Most brands have one language and an empty available_languages."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Rows per page. A value over the maximum reads as the maximum and sets filters_applied.limit_clamped. Allowed: 1\u2013100."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Rows to skip \u2014 the cursor for reading past `limit`. Default 0. While `has_more` is true, repeat with offset advanced by `returned_count`. Allowed: 0 or more."
          }
        ],
        "tags": [
          "Searches"
        ]
      }
    },
    "/prompts/leaderboard": {
      "get": {
        "summary": "Get Prompt Leaderboard",
        "operationId": "getPromptBrandLeaderboard",
        "description": "For ONE prompt: headline metrics plus every brand named on it, ranked. Requires brand_prompt_id from listQueries.",
        "responses": {
          "200": {
            "description": "Per-prompt brand leaderboard."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          },
          {
            "name": "brand_prompt_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Prompt ID token from listQueries."
          },
          {
            "name": "window_days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 30,
              "minimum": 1,
              "maximum": 365
            },
            "description": "Trailing window in days. A value outside the range is a 400. Allowed: 1\u2013365."
          }
        ],
        "tags": [
          "Prompts"
        ]
      }
    },
    "/prompts/by-visibility": {
      "get": {
        "summary": "List Prompts by Visibility",
        "operationId": "listPromptsByVisibility",
        "description": "Prompts ordered by visibility: ascending finds the gaps where the brand loses, descending finds the wins.",
        "responses": {
          "200": {
            "description": "Prompts ordered by visibility, each with its own net_sentiment so you can find the prompts the AIs talk about the brand badly in, not just the ones they omit it from. net_sentiment is -100..+100: how the AI platforms talk about the brand, not how often they name it. +100 = every labeled mention recommends it, -100 = every one criticizes it, 0 = balanced or uniformly neutral. It is computed over labeled mentions ONLY. sentiment_coverage_pct is what share of mentions carry a label; anything crawled before sentiment tracking began is unlabeled and counts toward neither side. Read the two together - net_sentiment 0 with coverage 0 means no data, not neutral, and must never be reported as neutral."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "asc",
              "enum": [
                "asc",
                "desc"
              ]
            },
            "description": "Sort direction."
          },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO start date (YYYY-MM-DD). Defaults to 30 days ago. The range may span at most 365 days; a longer one is a 400."
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO end date (YYYY-MM-DD). Defaults to today."
          },
          {
            "name": "query_tag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter to one tag slug."
          },
          {
            "name": "llm_provider",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "openai",
                "claude",
                "gemini",
                "perplexity",
                "grok"
              ]
            },
            "description": "Filter to one AI platform."
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO alpha-2 country code; 'ZZ' means Global."
          },
          {
            "name": "min_search_volume",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10
            },
            "description": "Minimum volume bucket. A value outside the range is a 400. Allowed: 1\u201310."
          },
          {
            "name": "max_difficulty",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10
            },
            "description": "Maximum difficulty bucket. A value outside the range is a 400. Allowed: 1\u201310."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Substring match on the prompt text."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Rows per page. A value over the maximum reads as the maximum and sets filters_applied.limit_clamped. Allowed: 1\u2013100."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Rows to skip \u2014 the cursor for reading past `limit`. Default 0. While `has_more` is true, repeat with offset advanced by `returned_count`. Allowed: 0 or more."
          }
        ],
        "tags": [
          "Prompts"
        ]
      }
    },
    "/prompts/ranking-advice": {
      "get": {
        "summary": "Get Ranking Advice for a Prompt",
        "operationId": "getRankingAdvice",
        "description": "Completed ranking-advice runs for ONE prompt \u2014 what to change to rank better. Read-only: this never starts a new run. Requires brand_prompt_id from listQueries.",
        "responses": {
          "200": {
            "description": "Ranking advice runs for the prompt. providers_scope lists the AI platforms each run's advice covers (empty with covers_all_providers true means every platform); name them when you relay advice that covers only some."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          },
          {
            "name": "brand_prompt_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Prompt ID token from listQueries."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10,
              "minimum": 1,
              "maximum": 50
            },
            "description": "Rows per page. A value over the maximum reads as the maximum and sets filters_applied.limit_clamped. Allowed: 1\u201350."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Rows to skip \u2014 the cursor for reading past `limit`. Default 0. While `has_more` is true, repeat with offset advanced by `returned_count`. Allowed: 0 or more."
          }
        ],
        "tags": [
          "Prompts"
        ]
      }
    },
    "/ranking-advice": {
      "get": {
        "summary": "List Ranking Advice Runs",
        "operationId": "listRankingAdvice",
        "description": "Ranking-advice runs across ALL of a brand's prompts. Use this to find which prompts already have advice before calling getRankingAdvice.",
        "responses": {
          "200": {
            "description": "Ranking advice runs for the brand, each with providers_scope: the AI platforms its advice covers."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 50
            },
            "description": "Rows per page. A value over the maximum reads as the maximum and sets filters_applied.limit_clamped. Allowed: 1\u201350."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Rows to skip \u2014 the cursor for reading past `limit`. Default 0. While `has_more` is true, repeat with offset advanced by `returned_count`. Allowed: 0 or more."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "done",
                "running",
                "pending",
                "error"
              ]
            },
            "description": "Lifecycle filter. Most callers want 'done'."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Substring match on the prompt text. Not the generated summary."
          }
        ],
        "tags": [
          "Prompts"
        ]
      }
    },
    "/ranking-advice/runs": {
      "post": {
        "summary": "Start Ranking Advice",
        "operationId": "startRankingAdvice",
        "description": "Start a ranking-advice run for one prompt, spending credits: the price getAccount lists under agents.ranking_advice, charged when the run starts and refunded if it fails. The run takes 5-12 minutes, so this answers at once with run_id and status; read the advice with getRankingAdvice once status is done. A finished run whose sources haven't changed comes back free, as does a run already in progress, and an account that can't pay gets error_code insufficient_credits; none of these starts a run or charges anything. started is true only when this call started one, and credits is what it spends. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand",
                  "brand_prompt_id"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  },
                  "brand_prompt_id": {
                    "type": "string",
                    "description": "Prompt ID token from listQueries."
                  },
                  "providers": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "openai",
                        "claude",
                        "gemini",
                        "perplexity",
                        "grok"
                      ]
                    },
                    "description": "AI platforms to build the advice from, e.g. ['openai'] for ChatGPT only. Omit for every platform the prompt runs on; one it doesn't run on is a 400."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The run started, or the existing run returned."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/query-runs": {
      "get": {
        "summary": "List Sample AI Answers",
        "operationId": "listQueryRuns",
        "description": "Recent AI answers for the brand's prompts, each with a short preview of the answer. To read one answer in full, take its run_id from this list and call getQueryRun.",
        "responses": {
          "200": {
            "description": "Sample AI answers, each with a ~300 character preview and a run_id. web_search_query_count is how many web searches the AI ran before answering: 0 means it answered without searching; null means the number is not recorded - Perplexity never exposes its searches, and runs from before we started recording them have no count. The search terms themselves are on getQueryRun. mention_sentiment is how that answer framed the brand - positive, neutral or negative. It is null when the answer never named the brand, and 'unknown' when it did but the run predates sentiment tracking; those are different facts, so do not read either as neutral. Only answers that have been read are listed; unparsed_run_count says how many more in the same scope are still waiting or failed to read."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          },
          {
            "name": "brand_prompt_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Limit to one prompt \u2014 token from listQueries."
          },
          {
            "name": "mentioned",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "true = only answers naming the brand; false = only answers that omit it; omit for both."
          },
          {
            "name": "llm_provider",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "openai",
                "claude",
                "gemini",
                "perplexity",
                "grok"
              ]
            },
            "description": "Filter to one AI platform."
          },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO start date (YYYY-MM-DD). Defaults to 30 days ago. The range may span at most 365 days; a longer one is a 400."
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO end date (YYYY-MM-DD). Defaults to today."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 5,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Rows per page. A value over the maximum reads as the maximum and sets filters_applied.limit_clamped. Allowed: 1\u2013100."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Rows to skip \u2014 the cursor for reading past `limit`. Default 0. While `has_more` is true, repeat with offset advanced by `returned_count`. Allowed: 0 or more."
          }
        ],
        "tags": [
          "Answers"
        ]
      }
    },
    "/query-runs/{run_id}": {
      "get": {
        "summary": "Get One AI Answer in Full",
        "operationId": "getQueryRun",
        "description": "One run in full: the complete answer text, every brand mentioned, every source cited and every web search the AI ran. Use this after listQueryRuns when the preview isn't enough.",
        "parameters": [
          {
            "name": "run_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Opaque run_id from listQueryRuns."
          }
        ],
        "responses": {
          "200": {
            "description": "The run, with full answer text. web_search_queries lists the searches the AI ran before answering, in order, as plain strings - the terms a brand has to rank for to be found for this prompt. An empty list with web_search_query_count 0 means the AI answered without searching; both null means the searches are not recorded - Perplexity never exposes them, and runs from before we started recording them have none. Each entry in mentions carries sentiment (positive, neutral, negative, or unknown when the run predates sentiment tracking) and sentiment_reason, the phrase in this answer that drove the label - null when there isn't one."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Answers"
        ]
      }
    },
    "/youtube/summaries": {
      "get": {
        "summary": "List YouTube Summaries",
        "operationId": "listYouTubeSummaries",
        "description": "Cited YouTube videos this brand has already paid to summarize. With no dates, every summary the brand owns is listed.",
        "responses": {
          "200": {
            "description": "YouTube summaries."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO start date (YYYY-MM-DD): only summaries completed on or after this day. Omit for no lower bound; with neither date, every summary the brand owns is listed. No maximum span."
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO end date (YYYY-MM-DD): only summaries completed on or before this day. Omit for no upper bound."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Substring match on video or channel title."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Rows per page. A value over the maximum reads as the maximum and sets filters_applied.limit_clamped. Allowed: 1\u2013100."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Rows to skip \u2014 the cursor for reading past `limit`. Default 0. While `has_more` is true, repeat with offset advanced by `returned_count`. Allowed: 0 or more."
          }
        ],
        "tags": [
          "Video"
        ]
      },
      "post": {
        "summary": "Summarize a YouTube Video",
        "operationId": "analyzeYouTubeVideo",
        "description": "Summarize a YouTube video the brand's answers cite, spending credits: 1 per 5 minutes of video, rounded up, at most 24, charged when the run starts and refunded if it fails. The run usually takes about a minute, so this answers at once with run_id and status; read the result with getYouTubeSummary. A video the brand already has a summary of comes back free, as does a run in progress. A video that can't be summarized, or an account that can't pay, comes back with status error and an error_code; none of these starts a run or charges anything. started is true only when this call started one, and credits is what it spends. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand",
                  "url"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  },
                  "url": {
                    "type": "string",
                    "description": "The YouTube URL as cited."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The run started, or the existing run returned."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/youtube/summary": {
      "get": {
        "summary": "Get YouTube Summary",
        "operationId": "getYouTubeSummary",
        "description": "Summary, key points and optional transcript for one cited YouTube URL. A brand whose run hasn't finished gets a 404 whose details carry its run_id, status and error_code.",
        "responses": {
          "200": {
            "description": "YouTube summary detail."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tracked brand name, exactly as returned by listTrackedBrands."
          },
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Full YouTube video URL."
          },
          {
            "name": "include_transcript",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Include the full transcript text."
          }
        ],
        "tags": [
          "Video"
        ]
      }
    },
    "/prompts/archive": {
      "post": {
        "summary": "Archive Prompts",
        "operationId": "archivePrompts",
        "description": "Stop running prompts on every AI platform. Their results stay in the charts, and restorePrompts brings them back. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand",
                  "brand_prompt_ids"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  },
                  "brand_prompt_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 200,
                    "description": "Prompt ID tokens from listQueries. Allowed: 1\u2013200 items."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done. The body reports the outcome for each item."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/prompts/restore": {
      "post": {
        "summary": "Restore Prompts",
        "operationId": "restorePrompts",
        "description": "Run archived prompts again on the AI platforms they were removed from, as far as the plan's prompt runs allow. A restored prompt is checked within the hour. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand",
                  "brand_prompt_ids"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  },
                  "brand_prompt_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 200,
                    "description": "Prompt ID tokens from listQueries. Allowed: 1\u2013200 items."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done. The body reports the outcome for each item."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/prompts/llms": {
      "post": {
        "summary": "Change Prompts' AI Platforms",
        "operationId": "updatePromptLLMs",
        "description": "Add or remove AI platforms on prompts. Removals apply first, so the prompt runs they free count toward the additions in the same call. In a workspace already over its prompt-run limit, a note says how many added pairs won't run until runs free up. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand",
                  "brand_prompt_ids"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  },
                  "brand_prompt_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 200,
                    "description": "Prompt ID tokens from listQueries. Allowed: 1\u2013200 items."
                  },
                  "add_llms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 5,
                    "description": "Platform slugs to add (see getAccount). Allowed: up to 5 items."
                  },
                  "remove_llms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 5,
                    "description": "Platform slugs to remove. Allowed: up to 5 items."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done. The body reports the outcome for each item."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/prompts/tags": {
      "post": {
        "summary": "Tag or Untag Prompts",
        "operationId": "updatePromptTags",
        "description": "Add tags to prompts or remove them. An added tag that doesn't exist yet is created. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand",
                  "brand_prompt_ids"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  },
                  "brand_prompt_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 200,
                    "description": "Prompt ID tokens from listQueries. Allowed: 1\u2013200 items."
                  },
                  "add_tags": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 100
                    },
                    "maxItems": 10,
                    "description": "Tags to attach to every prompt in the call. Repeats, ignoring case and spacing, don't count toward the maximum. More than the maximum, or a tag over the length limit, is a 400. Allowed: up to 10 items, each up to 100 characters."
                  },
                  "remove_tags": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 100
                    },
                    "maxItems": 10,
                    "description": "Tag names or slugs to remove. Allowed: up to 10 items, each up to 100 characters."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done. The body reports the outcome for each item."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/brands/check-now": {
      "post": {
        "summary": "Check a Brand Now",
        "operationId": "runBrandNow",
        "description": "Queue the brand's prompts to run at the next scheduler tick, within 15 minutes. Prompts already checked in the current cadence period (today since 00:00 UTC on a daily brand, otherwise the last cadence_days) are skipped. Asking again in the same period re-runs only prompts whose check failed. The brand's regular schedule doesn't move. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The outcome: queued, or why nothing was queued."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/brands/archive": {
      "post": {
        "summary": "Stop Tracking a Brand",
        "operationId": "archiveTrackedBrand",
        "description": "Stop tracking a brand. Its history is kept, and addTrackedBrand with the same name tracks it again. The workspace's last brand can't be archived. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The outcome: archived, or why it wasn't."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/brands/competitors/remove": {
      "post": {
        "summary": "Remove Competitors",
        "operationId": "removeCompetitors",
        "description": "Permanently remove competitors. Each one's aliases and owned domains are deleted with it, and this can't be undone. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand",
                  "competitors"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  },
                  "competitors": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 255
                    },
                    "minItems": 1,
                    "maxItems": 50,
                    "description": "Competitor names from listCompetitors. Allowed: 1\u201350 items, each up to 255 characters."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done. The body reports the outcome for each item."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/brands/aliases/remove": {
      "post": {
        "summary": "Remove Aliases",
        "operationId": "removeAliases",
        "description": "Permanently remove aliases from the brand or one of its competitors. This can't be undone. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand",
                  "aliases"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  },
                  "aliases": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 255
                    },
                    "minItems": 1,
                    "maxItems": 50,
                    "description": "Aliases from listAliases. Allowed: 1\u201350 items, each up to 255 characters."
                  },
                  "match_mode": {
                    "type": "string",
                    "enum": [
                      "exact",
                      "contains"
                    ],
                    "description": "Remove only the aliases with this match mode. Omit it to remove both modes."
                  },
                  "competitor": {
                    "type": "string",
                    "description": "A competitor's name, from listCompetitors, to act on that competitor. Omit it to act on the brand itself."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done. The body reports the outcome for each item."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/brands/owned-domains": {
      "post": {
        "summary": "Add Owned Domains",
        "operationId": "addOwnedDomains",
        "description": "Declare domains as the brand's own, or a competitor's. Citations of them are then labelled yours or competitor:<name> instead of earned. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand",
                  "domains"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  },
                  "domains": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 255
                    },
                    "minItems": 1,
                    "maxItems": 50,
                    "description": "Domains, e.g. example.com. Allowed: 1\u201350 items, each up to 255 characters."
                  },
                  "competitor": {
                    "type": "string",
                    "description": "A competitor's name, from listCompetitors, to act on that competitor. Omit it to act on the brand itself."
                  },
                  "include_subdomains": {
                    "type": "boolean",
                    "default": true,
                    "description": "Match subdomains too."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done. The body reports the outcome for each item."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/brands/owned-domains/remove": {
      "post": {
        "summary": "Remove Owned Domains",
        "operationId": "removeOwnedDomains",
        "description": "Permanently remove declared domains from the brand or one of its competitors. Their citations read as earned again. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand",
                  "domains"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  },
                  "domains": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 255
                    },
                    "minItems": 1,
                    "maxItems": 50,
                    "description": "Declared domains to remove. Allowed: 1\u201350 items, each up to 255 characters."
                  },
                  "competitor": {
                    "type": "string",
                    "description": "A competitor's name, from listCompetitors, to act on that competitor. Omit it to act on the brand itself."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done. The body reports the outcome for each item."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/queries/tags/update": {
      "post": {
        "summary": "Rename or Recolor a Tag",
        "operationId": "updateTag",
        "description": "Rename a prompt tag or change its color. The prompts carrying it keep it, and its slug follows the new name. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand",
                  "tag"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  },
                  "tag": {
                    "type": "string",
                    "description": "The tag's name or slug."
                  },
                  "name": {
                    "type": "string",
                    "description": "The new name, up to 100 characters."
                  },
                  "color": {
                    "type": "string",
                    "description": "The new color, e.g. #0075ca."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done. The body reports the outcome for each item."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/queries/tags/delete": {
      "post": {
        "summary": "Delete a Tag",
        "operationId": "deleteTag",
        "description": "Permanently delete a prompt tag. The prompts that carried it stay tracked and lose only the tag. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand",
                  "tag"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  },
                  "tag": {
                    "type": "string",
                    "description": "The tag's name or slug."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done. The body reports the outcome for each item."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    },
    "/prompts": {
      "post": {
        "summary": "Add Prompts to Track",
        "operationId": "addPrompts",
        "description": "Add prompts to track for a brand across the chosen AI platforms and queue the first crawl. Requires a write-enabled API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brand",
                  "prompts",
                  "llms"
                ],
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Tracked brand name."
                  },
                  "prompts": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 2000
                    },
                    "minItems": 1,
                    "maxItems": 50,
                    "description": "The prompts to track. Blank and repeated ones don't count toward the maximum. More than the maximum, or a prompt over the length limit, is a 400. Allowed: 1\u201350 items, each up to 2,000 characters."
                  },
                  "llms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "description": "Platform slugs the plan allows, e.g. ['openai', 'claude']. Allowed: 1 or more items."
                  },
                  "country": {
                    "type": "string",
                    "default": "ZZ",
                    "description": "ISO alpha-2 code; 'ZZ' or omitted = Global. An unsupported code is a 400, not Global."
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 100
                    },
                    "maxItems": 10,
                    "description": "Tags to attach to every prompt in the call. Repeats, ignoring case and spacing, don't count toward the maximum. More than the maximum, or a tag over the length limit, is a 400. Allowed: up to 10 items, each up to 100 characters."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Prompts added and crawl queued."
          },
          "400": {
            "description": "Validation error \u2014 check the message in `error.message`."
          },
          "401": {
            "description": "Unauthorized \u2014 missing, invalid or revoked bearer token."
          },
          "403": {
            "description": "Forbidden \u2014 the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit."
          },
          "404": {
            "description": "Not found \u2014 the brand, prompt or resource does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Too many requests \u2014 over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Internal error \u2014 logged; retry is safe for reads."
          }
        },
        "tags": [
          "Writes"
        ]
      }
    }
  },
  "tags": [
    {
      "name": "Discovery",
      "description": "Find the brands, competitors, prompts, tags and AI platforms this workspace tracks. Start here \u2014 most other endpoints take a brand name or prompt ID returned by these."
    },
    {
      "name": "Visibility",
      "description": "How often the brand appears in AI answers, and who it shares those answers with."
    },
    {
      "name": "Citations",
      "description": "The pages and domains AI platforms cite when they answer, and how much of that is your own."
    },
    {
      "name": "Searches",
      "description": "The web searches the AI platforms actually ran while answering a prompt."
    },
    {
      "name": "Prompts",
      "description": "Per-prompt standings and the advice agent's guidance on improving them."
    },
    {
      "name": "Answers",
      "description": "The raw AI answers behind every metric, in full."
    },
    {
      "name": "Video",
      "description": "Summaries of cited YouTube videos the brand has paid to analyze."
    },
    {
      "name": "Writes",
      "description": "Change what the workspace tracks: its brands, prompts, tags, competitors, aliases and owned domains. These need a write-enabled API key."
    }
  ]
}