{"openapi":"3.1.0","info":{"title":"Heralded API","summary":"Read your brands' AI visibility and run Snapshots in Heralded.","description":"Access to one organization's brands, as the member who created the API key. A read-only key reads; a full-access key also starts, edits and runs that member's Snapshots on the organization's Snapshot credits. Each key may make 120 requests a minute. Separate organization service tokens can start Snapshots and Full audits and read service audits. Every error is an RFC 9457 problem (`application/problem+json`) whose `code` names it.","version":"1"},"servers":[{"url":"https://api.heralded.ai"}],"paths":{"/v1/brands":{"get":{"tags":["v1"],"summary":"Get Brands","description":"The brands your credential reads; managed:read includes actively managed organizations.","operationId":"listBrands","security":[{"serviceToken":[]},{"apiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum brands to return.","default":100,"title":"Limit"},"description":"Maximum brands to return."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Brands"}}}},"404":{"description":"No resource this caller can read.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/brands/{brand_id}/snapshots":{"get":{"tags":["v1"],"summary":"Get Brand Snapshots","description":"Unlocked full Snapshots, including the baseline, newest first. Figures\nmatch each Snapshot's issued report. Service tokens need managed:read.","operationId":"getBrandSnapshots","security":[{"serviceToken":[]},{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only Snapshots measured strictly before this date-time.","title":"Before"},"description":"Only Snapshots measured strictly before this date-time."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":52,"minimum":1,"description":"Maximum Snapshots to return, from 1 to 52.","default":8,"title":"Limit"},"description":"Maximum Snapshots to return, from 1 to 52."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1BrandSnapshots"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}}}}},"/v1/brands/{brand_id}/snapshots/{share_id}/share":{"post":{"tags":["v1"],"summary":"Share Brand Snapshot","description":"Make a restricted Snapshot unlisted and return its URL. Public links\nkeep their URL; revoked links stay revoked. Members need the existing\nSnapshot sharing permission; service tokens need managed:share.","operationId":"shareBrandSnapshot","security":[{"serviceToken":[]},{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"share_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The report link id from getBrandSnapshots.","title":"Share Id"},"description":"The report link id from getBrandSnapshots."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SnapshotShare"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The Snapshot's link is revoked.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#snapshot_revoked","title":"Conflict","status":409,"detail":"Conflict","code":"snapshot_revoked","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}}}}},"/v1/brands/{brand_id}/profile":{"get":{"tags":["v1"],"summary":"Get Brand Profile","description":"Current brand identity, confirmed buyer context over inference, facts,\nthe Default segment's market and owned-domain review state. Read-only;\nedits appear immediately without changing past scans.","operationId":"getBrandProfile","security":[{"serviceToken":[]},{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1BrandProfile"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}}}}},"/v1/brands/{brand_id}/overview":{"get":{"tags":["v1"],"summary":"Get Overview","description":"A brand's figures over the selected period with ranges, states and change,\nthe score's band, the latest weekly report and citation metrics, the top\nfive rivals, the five most cited sources and the five newest open actions, the next\nweekly and daily scan times, the daily scans since the last weekly scan, the open\naction count, how many pages AI engines cannot read, what the score was read from,\nits move since the first weekly scan and the work verified as paying off.\n`with_diagnosis` adds what rivals win over the last week. `lean` leaves out the\nrivals, sources, actions, attribution and readiness.","operationId":"getOverview","security":[{"serviceToken":[]},{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"side","in":"query","required":false,"schema":{"enum":["all","ai","search"],"type":"string","description":"Read AI answers (ai), Google shares without a score (search), or AI figures (all).","default":"all","title":"Side"},"description":"Read AI answers (ai), Google shares without a score (search), or AI figures (all)."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"with_diagnosis","in":"query","required":false,"schema":{"type":"boolean","description":"Add `diagnosis`: the prompts and sources rivals win over the last week, and the drafts ready to answer them.","default":false,"title":"With Diagnosis"},"description":"Add `diagnosis`: the prompts and sources rivals win over the last week, and the drafts ready to answer them."},{"name":"lean","in":"query","required":false,"schema":{"type":"boolean","description":"Omit `rivals`, `sources`, `actions`, `attribution` and `readiness`, and read none of them. They come back empty or null, and `source_citation_evidence` and `source_unavailable_scans` stay at their defaults; every other field is unchanged.","default":false,"title":"Lean"},"description":"Omit `rivals`, `sources`, `actions`, `attribution` and `readiness`, and read none of them. They come back empty or null, and `source_citation_evidence` and `source_unavailable_scans` stay at their defaults; every other field is unchanged."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Overview"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}}}}},"/v1/brands/{brand_id}/scores":{"get":{"tags":["v1"],"summary":"Get Scores","description":"All five figures over the selected period, with ranges, states, change and trends,\nover the answers the engine, type, intent, topic, segment and prompt filters keep, and\nper group under `group_by`. `include` also returns the Engines table or pane.","operationId":"getScores","security":[{"serviceToken":[]},{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Check country or global. Omit for all.","title":"Country"},"description":"Check country or global. Omit for all."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":10,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"side","in":"query","required":false,"schema":{"enum":["all","ai","search"],"type":"string","description":"Read AI answers (ai), Google shares without a score (search), or AI figures (all).","default":"all","title":"Side"},"description":"Read AI answers (ai), Google shares without a score (search), or AI figures (all)."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"preview","in":"query","required":false,"schema":{"type":"boolean","description":"Include the selected engine’s bounded Work preview. Select a figure with pane_axis.","default":false,"title":"Preview"},"description":"Include the selected engine’s bounded Work preview. Select a figure with pane_axis."},{"name":"pane_axis","in":"query","required":false,"schema":{"anyOf":[{"enum":["mentioned","recommended","understood","praised"],"type":"string"},{"type":"null"}],"description":"Read only this figure, including its bounded evidence.","title":"Pane Axis"},"description":"Read only this figure, including its bounded evidence."},{"name":"section","in":"query","required":false,"schema":{"anyOf":[{"enum":["weakest","strongest","sources","brands","work","questions","claims","rankings","ranking_pages","markets"],"type":"string"},{"type":"null"}],"description":"The selected section paged by limit and offset.","title":"Section"},"description":"The selected section paged by limit and offset."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"with_panes","in":"query","required":false,"schema":{"type":"boolean","description":"Include figure details.","default":false,"title":"With Panes"},"description":"Include figure details."},{"name":"with_search_detail","in":"query","required":false,"schema":{"type":"boolean","description":"Include Google rankings, pages, brands, markets and actions with side=search and either with_panes=true or pane_axis, scoped by topic, market and audience.","default":false,"title":"With Search Detail"},"description":"Include Google rankings, pages, brands, markets and actions with side=search and either with_panes=true or pane_axis, scoped by topic, market and audience."},{"name":"figure_only","in":"query","required":false,"schema":{"type":"boolean","description":"Return figures without supporting tables. Deprecated; sunset 2026-11-23.","deprecated":true,"default":false,"title":"Figure Only"},"description":"Return figures without supporting tables. Deprecated; sunset 2026-11-23.","deprecated":true},{"name":"group_by","in":"query","required":false,"schema":{"anyOf":[{"enum":["engine","intent","stage","type","topic","prompt","competitor","country"],"type":"string"},{"type":"null"}],"description":"Also state the figures per engine, intent, stage, prompt type, topic, prompt, competitor or country asked from, under the same period and filters.","title":"Group By"},"description":"Also state the figures per engine, intent, stage, prompt type, topic, prompt, competitor or country asked from, under the same period and filters."},{"name":"include","in":"query","required":false,"schema":{"anyOf":[{"enum":["engines","engine"],"type":"string"},{"type":"null"}],"description":"Include the Engines table or details for the selected engine.","title":"Include"},"description":"Include the Engines table or details for the selected engine."},{"name":"sort","in":"query","required":false,"schema":{"enum":["engine","score","trend","mentioned","recommended","understood","praised","answers"],"type":"string","description":"Field to order results by.","default":"score","title":"Sort"},"description":"Field to order results by."},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"description":"Order results ascending or descending.","title":"Direction"},"description":"Order results ascending or descending."},{"name":"with_menus","in":"query","required":false,"schema":{"type":"boolean","description":"Include available filter choices.","default":false,"title":"With Menus"},"description":"Include available filter choices."},{"name":"with_cards","in":"query","required":false,"schema":{"type":"boolean","description":"Include figure summaries.","default":false,"title":"With Cards"},"description":"Include figure summaries."},{"name":"with_trend","in":"query","required":false,"schema":{"type":"boolean","description":"Include each figure's weekly trend. Without it, `trend` is empty.","default":true,"title":"With Trend"},"description":"Include each figure's weekly trend. Without it, `trend` is empty."},{"name":"you","in":"query","required":false,"schema":{"anyOf":[{"enum":["named","not_named"],"type":"string"},{"type":"null"}],"description":"Keep prompts or answers matching this brand-presence state.","title":"You"},"description":"Keep prompts or answers matching this brand-presence state."},{"name":"you_engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"const":"all","type":"string"},{"type":"null"}],"description":"Resolve `you` on this engine, or `all` engines, before measuring the selected `engine`. Omit to resolve `you` under the engine filter.","title":"You Engine"},"description":"Resolve `you` on this engine, or `all` engines, before measuring the selected `engine`. Omit to resolve `you` under the engine filter."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"topic_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Deprecated topic selector; use topic for a tracked topic UUID.","deprecated":true,"title":"Topic Id"},"description":"Deprecated topic selector; use topic for a tracked topic UUID.","deprecated":true}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Scores"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}}}}},"/v1/brands/{brand_id}/prompts":{"get":{"tags":["v1"],"summary":"Get Prompts","description":"The tracked prompts and how each engine's latest answer treated the brand.","operationId":"listPrompts","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Check country or global. Omit for all.","title":"Country"},"description":"Check country or global. Omit for all."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"Text to search for.","title":"Q"},"description":"Text to search for."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"4w","title":"Period"},"description":"Weekly-report period."},{"name":"prompt_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Select a prompt type.","title":"Prompt Type"},"description":"Select a prompt type."},{"name":"topic_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Select a topic by id, or untagged for prompts without a topic.","title":"Topic Id"},"description":"Select a topic by id, or untagged for prompts without a topic."},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"enum":["volume","change","presence","name","prompt","score","trend"],"type":"string"},{"type":"null"}],"description":"Field to order results by.","title":"Sort"},"description":"Field to order results by."},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"description":"Order results ascending or descending.","title":"Direction"},"description":"Order results ascending or descending."},{"name":"you","in":"query","required":false,"schema":{"anyOf":[{"enum":["named","not_named"],"type":"string"},{"type":"null"}],"description":"Keep prompts or answers matching this brand-presence state.","title":"You"},"description":"Keep prompts or answers matching this brand-presence state."},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean","description":"Include archived prompts.","default":false,"title":"Archived"},"description":"Include archived prompts."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Prompts"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/prompts/{prompt_uid}":{"get":{"tags":["v1"],"summary":"Get Prompt","description":"One question's figures, latest answers and leading brands.\n\nUse with_details for engine cards and Google searches. Markets and searches have\nseparate paging parameters.","operationId":"getPrompt","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"prompt_uid","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The prompt id from list_prompts.","title":"Prompt Uid"},"description":"The prompt id from list_prompts."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Check country or global. Omit for all.","title":"Country"},"description":"Check country or global. Omit for all."},{"name":"with_details","in":"query","required":false,"schema":{"type":"boolean","description":"Include engine cards and paged Google searches.","default":true,"title":"With Details"},"description":"Include engine cards and paged Google searches."},{"name":"with_engine_cards","in":"query","required":false,"schema":{"type":"boolean","description":"Include engine cards with details.","default":true,"title":"With Engine Cards"},"description":"Include engine cards with details."},{"name":"with_searches","in":"query","required":false,"schema":{"type":"boolean","description":"Include Google searches with details.","default":true,"title":"With Searches"},"description":"Include Google searches with details."},{"name":"wordings_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"description":"Current markets to return; the compact read defaults to five.","title":"Wordings Limit"},"description":"Current markets to return; the compact read defaults to five."},{"name":"wordings_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Current markets to skip.","default":0,"title":"Wordings Offset"},"description":"Current markets to skip."},{"name":"wordings_language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Language code of current markets.","title":"Wordings Language"},"description":"Language code of current markets."},{"name":"searches_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"description":"Google searches to return; omitted returns all.","title":"Searches Limit"},"description":"Google searches to return; omitted returns all."},{"name":"searches_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Google searches to skip.","default":0,"title":"Searches Offset"},"description":"Google searches to skip."},{"name":"sources_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Cited sites per page.","default":5,"title":"Sources Limit"},"description":"Cited sites per page."},{"name":"sources_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Cited sites to skip.","default":0,"title":"Sources Offset"},"description":"Cited sites to skip."},{"name":"competitors_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"description":"Brands per page.","title":"Competitors Limit"},"description":"Brands per page."},{"name":"competitors_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Brands to skip.","default":0,"title":"Competitors Offset"},"description":"Brands to skip."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1PromptDetail"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/changes":{"get":{"tags":["v1"],"summary":"Get Changes","description":"Home's changes since the latest weekly scan, newest first, including new competitors.\n\nRows collapse by kind and subject. `writing` means the scan's changes are still\nbeing written. Reading does not mark changes seen; viewer markers stay in the app.","operationId":"listChanges","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Changes"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/answers":{"get":{"tags":["v1"],"summary":"Get Answers","description":"The engines' answers, newest first, optionally for one prompt, engine or named brand.","operationId":"listAnswers","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"Text to search for.","title":"Q"},"description":"Text to search for."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"period","in":"query","required":false,"schema":{"anyOf":[{"enum":["1w","4w","12w","all"],"type":"string"},{"type":"null"}],"description":"Weekly-report period; omitted for all weekly and daily answers.","title":"Period"},"description":"Weekly-report period; omitted for all weekly and daily answers."},{"name":"read_since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Keep answers whose run completed at or after this ISO 8601 time. With `period=all` it reads every weekly and daily answer once, as without `period`.","title":"Read Since"},"description":"Keep answers whose run completed at or after this ISO 8601 time. With `period=all` it reads every weekly and daily answer once, as without `period`."},{"name":"names","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Only answers that name this brand, such as a rival's name.","title":"Names"},"description":"Only answers that name this brand, such as a rival's name."},{"name":"you","in":"query","required":false,"schema":{"anyOf":[{"enum":["named","recommended","not_named"],"type":"string"},{"type":"null"}],"description":"Keep prompts or answers matching this brand-presence state.","title":"You"},"description":"Keep prompts or answers matching this brand-presence state."},{"name":"cites","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Keep answers citing this URL or domain.","title":"Cites"},"description":"Keep answers citing this URL or domain."},{"name":"source_group","in":"query","required":false,"schema":{"anyOf":[{"enum":["own","rival","review","editorial","community","vendor","other"],"type":"string"},{"const":"independent","type":"string"},{"type":"null"}],"description":"Keep answers citing this source group.","title":"Source Group"},"description":"Keep answers citing this source group."},{"name":"cited_page","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Keep answers citing this page.","title":"Cited Page"},"description":"Keep answers citing this page."},{"name":"claim","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"A claim key from the claims list.","title":"Claim"},"description":"A claim key from the claims list."},{"name":"claim_wording","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"The exact wording of the selected claim.","title":"Claim Wording"},"description":"The exact wording of the selected claim."},{"name":"content_topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"Filter by the measured subject of a cited page.","title":"Content Topic"},"description":"Filter by the measured subject of a cited page."},{"name":"action","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"An action id whose supporting answers to read.","title":"Action"},"description":"An action id whose supporting answers to read."},{"name":"sort","in":"query","required":false,"schema":{"enum":["time","sources"],"type":"string","description":"Field to order results by.","default":"time","title":"Sort"},"description":"Field to order results by."},{"name":"direction","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","description":"Order results ascending or descending.","default":"desc","title":"Direction"},"description":"Order results ascending or descending."},{"name":"with_menus","in":"query","required":false,"schema":{"type":"boolean","description":"Include available filter choices.","default":false,"title":"With Menus"},"description":"Include available filter choices."},{"name":"prompt_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt Id"},"description":"Question id from list_prompts."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Answers"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/answers/{answer_id}":{"get":{"tags":["v1"],"summary":"Get Answer","description":"One answer in full, with the pages it cited and the rivals it named.","operationId":"getAnswer","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"answer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"An answer id from list_answers.","title":"Answer Id"},"description":"An answer id from list_answers."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Answer"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/competitors":{"get":{"tags":["v1"],"summary":"Get Competitors","description":"The brand and its rivals, ranked by Heralded Score on AI or Mentioned on Search.\n\n`with_page` adds the competitor leaderboard and roster capacity.\n`with_details` also includes weekly sites, moves and stored AI descriptions.","operationId":"listCompetitors","security":[{"serviceToken":[]},{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Check country or global. Omit for all.","title":"Country"},"description":"Check country or global. Omit for all."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"side","in":"query","required":false,"schema":{"enum":["all","ai","search"],"type":"string","description":"Read AI answers (ai), Google shares without a score (search), or AI figures (all).","default":"all","title":"Side"},"description":"Read AI answers (ai), Google shares without a score (search), or AI figures (all)."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"with_details","in":"query","required":false,"schema":{"type":"boolean","description":"Include the page, weekly competitor sites and moves, and AI descriptions.","default":false,"title":"With Details"},"description":"Include the page, weekly competitor sites and moves, and AI descriptions."},{"name":"you","in":"query","required":false,"schema":{"anyOf":[{"enum":["named","not_named"],"type":"string"},{"type":"null"}],"description":"Keep prompts or answers matching this brand-presence state.","title":"You"},"description":"Keep prompts or answers matching this brand-presence state."},{"name":"topic_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Select a topic by id, or untagged for prompts without a topic.","title":"Topic Id"},"description":"Select a topic by id, or untagged for prompts without a topic."},{"name":"with_page","in":"query","required":false,"schema":{"type":"boolean","description":"Include competitor website details.","default":false,"title":"With Page"},"description":"Include competitor website details."},{"name":"with_menus","in":"query","required":false,"schema":{"type":"boolean","description":"Include available filter choices.","default":false,"title":"With Menus"},"description":"Include available filter choices."},{"name":"with_trend","in":"query","required":false,"schema":{"type":"boolean","description":"Include each figure's weekly trend. Without it, `trend` is empty.","default":true,"title":"With Trend"},"description":"Include each figure's weekly trend. Without it, `trend` is empty."},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"enum":["brand","score","trend","mentioned","recommended","product_cards"],"type":"string"},{"type":"null"}],"description":"Order the leaderboard by this figure. Defaults to Mentioned descending on Search, or Heralded Score descending on AI and All.","title":"Sort"},"description":"Order the leaderboard by this figure. Defaults to Mentioned descending on Search, or Heralded Score descending on AI and All."},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"description":"Order results ascending or descending.","title":"Direction"},"description":"Order results ascending or descending."},{"name":"discovered_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum discovered competitors to return.","default":10,"title":"Discovered Limit"},"description":"Maximum discovered competitors to return."},{"name":"discovered_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Discovered competitors to skip.","default":0,"title":"Discovered Offset"},"description":"Discovered competitors to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Competitors"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}}}}},"/v1/brands/{brand_id}/competitors/{key}":{"get":{"tags":["v1"],"summary":"Get Competitor","description":"One competitor's period score, trend, comparisons, prompts, engines and cited pages.\n\n`page_url` also opens its rival-page pane, including daily-only discoveries.\nWith it, key can be the page's hostname instead of the competitor's brand key.\n`with_details` adds weekly site changes and stored AI descriptions.","operationId":"getCompetitor","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"key","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":300,"description":"A competitor key from list_competitors.","title":"Key"},"description":"A competitor key from list_competitors."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Check country or global. Omit for all.","title":"Country"},"description":"Check country or global. Omit for all."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"side","in":"query","required":false,"schema":{"enum":["all","ai","search"],"type":"string","description":"Read AI answers (ai), Google shares without a score (search), or AI figures (all).","default":"all","title":"Side"},"description":"Read AI answers (ai), Google shares without a score (search), or AI figures (all)."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"preview","in":"query","required":false,"schema":{"type":"boolean","description":"Return bounded section previews.","default":false,"title":"Preview"},"description":"Return bounded section previews."},{"name":"section","in":"query","required":false,"schema":{"anyOf":[{"enum":["lost","won","pages","questions","work","website","changes"],"type":"string"},{"type":"null"}],"description":"The section paged by limit and offset.","title":"Section"},"description":"The section paged by limit and offset."},{"name":"with_details","in":"query","required":false,"schema":{"type":"boolean","description":"Include weekly site changes and how AI describes this brand.","default":false,"title":"With Details"},"description":"Include weekly site changes and how AI describes this brand."},{"name":"you","in":"query","required":false,"schema":{"anyOf":[{"enum":["named","not_named"],"type":"string"},{"type":"null"}],"description":"Keep prompts or answers matching this brand-presence state.","title":"You"},"description":"Keep prompts or answers matching this brand-presence state."},{"name":"topic_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Select a topic by id, or untagged for prompts without a topic.","title":"Topic Id"},"description":"Select a topic by id, or untagged for prompts without a topic."},{"name":"page_url","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}],"description":"Also return this competitor-owned page's details, including daily-only discoveries.","title":"Page Url"},"description":"Also return this competitor-owned page's details, including daily-only discoveries."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1CompetitorDetail"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/competitors/{key}/page":{"get":{"tags":["v1"],"summary":"Get Competitor Page","description":"Read one competitor page’s history, questions and URL-targeted Work.","operationId":"getCompetitorPage","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand’s UUID from listBrands.","title":"Brand Id"},"description":"The brand’s UUID from listBrands."},{"name":"key","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":300,"description":"The competitor key or page hostname.","title":"Key"},"description":"The competitor key or page hostname."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Check country or global. Omit for all.","title":"Country"},"description":"Check country or global. Omit for all."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"page_url","in":"query","required":true,"schema":{"type":"string","maxLength":4096,"description":"The competitor page URL to read.","title":"Page Url"},"description":"The competitor page URL to read."},{"name":"section","in":"query","required":false,"schema":{"anyOf":[{"enum":["questions","work"],"type":"string"},{"type":"null"}],"description":"Page this section with limit and offset; omit for both previews.","title":"Section"},"description":"Page this section with limit and offset; omit for both previews."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1RivalPageRead"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/sources":{"get":{"tags":["v1"],"summary":"Get Sources","description":"Sites found through AI citations, Google rankings or monitoring in the period.","operationId":"listSources","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"owner","in":"query","required":false,"schema":{"anyOf":[{"enum":["third_party","competitor","yours"],"type":"string"},{"type":"null"}],"description":"Filter by who owns the source.","title":"Owner"},"description":"Filter by who owns the source."},{"name":"source_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["industry_authority","review","regulatory","media","educational","community","consulting","social","vendor","directory","unclassified"],"type":"string"},{"const":"corporate","type":"string"},{"type":"null"}],"description":"Filter by source category.","title":"Source Type"},"description":"Filter by source category."},{"name":"names_you","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Keep sources that name the brand, or exclude them when false.","title":"Names You"},"description":"Keep sources that name the brand, or exclude them when false."},{"name":"content_topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"description":"Filter by the measured subject of a cited page.","title":"Content Topic"},"description":"Filter by the measured subject of a cited page."},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}],"description":"A source domain, including its subdomains, such as g2.com.","title":"Domain"},"description":"A source domain, including its subdomains, such as g2.com."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Text to search for.","title":"Q"},"description":"Text to search for."},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"description":"Order results ascending or descending.","title":"Direction"},"description":"Order results ascending or descending."},{"name":"with_menus","in":"query","required":false,"schema":{"type":"boolean","description":"Include available filter choices.","default":false,"title":"With Menus"},"description":"Include available filter choices."},{"name":"with_trend","in":"query","required":false,"schema":{"type":"boolean","description":"Include weekly card figures and their adjacent-window changes.","default":false,"title":"With Trend"},"description":"Include weekly card figures and their adjacent-window changes."},{"name":"muted","in":"query","required":false,"schema":{"type":"boolean","description":"List only muted sites when true.","default":false,"title":"Muted"},"description":"List only muted sites when true."},{"name":"opening","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter sites by a pitchable opening that does not name you.","title":"Opening"},"description":"Filter sites by a pitchable opening that does not name you."},{"name":"sells_placements","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Keep sites known to sell placements, or exclude them when false.","title":"Sells Placements"},"description":"Keep sites known to sell placements, or exclude them when false."},{"name":"with_summary","in":"query","required":false,"schema":{"type":"boolean","description":"Include source summary counts.","default":false,"title":"With Summary"},"description":"Include source summary counts."},{"name":"sort","in":"query","required":false,"schema":{"enum":["domain","citations","answers","change","priority","recommends_you","read_by_searchers"],"type":"string","description":"Field to order results by.","default":"citations","title":"Sort"},"description":"Field to order results by."},{"name":"found_via","in":"query","required":false,"schema":{"anyOf":[{"enum":["ai_citation","google_ranking","monitor"],"type":"string"},{"type":"null"}],"description":"Filter by how the source was found.","title":"Found Via"},"description":"Filter by how the source was found."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Sources"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/sources/{domain}":{"get":{"tags":["v1"],"summary":"Get Source","description":"One cited site's facts, pages, prompts, engines and citation history under shared filters.","operationId":"getSource","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"domain","in":"path","required":true,"schema":{"type":"string","description":"A source domain, such as g2.com.","title":"Domain"},"description":"A source domain, such as g2.com."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"content_topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"description":"Filter by the measured subject of a cited page.","title":"Content Topic"},"description":"Filter by the measured subject of a cited page."},{"name":"actions_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":0,"description":"Maximum related actions to return; zero omits them.","default":0,"title":"Actions Limit"},"description":"Maximum related actions to return; zero omits them."},{"name":"actions_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Related actions to skip.","default":0,"title":"Actions Offset"},"description":"Related actions to skip."},{"name":"prompts_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum related prompts to return.","default":10,"title":"Prompts Limit"},"description":"Maximum related prompts to return."},{"name":"prompts_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Related prompts to skip.","default":0,"title":"Prompts Offset"},"description":"Related prompts to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SourceDetail"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/cited-pages":{"get":{"tags":["v1"],"summary":"Get Cited Pages","description":"Cited page rows under the period and shared filters, including engine.","operationId":"listCitedPages","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"owner","in":"query","required":false,"schema":{"anyOf":[{"enum":["third_party","competitor","yours"],"type":"string"},{"type":"null"}],"description":"Filter by who owns the source.","title":"Owner"},"description":"Filter by who owns the source."},{"name":"source_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["industry_authority","review","regulatory","media","educational","community","consulting","social","vendor","directory","unclassified"],"type":"string"},{"const":"corporate","type":"string"},{"type":"null"}],"description":"Filter by source category.","title":"Source Type"},"description":"Filter by source category."},{"name":"names_you","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Keep sources that name the brand, or exclude them when false.","title":"Names You"},"description":"Keep sources that name the brand, or exclude them when false."},{"name":"content_topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"description":"Filter by the measured subject of a cited page.","title":"Content Topic"},"description":"Filter by the measured subject of a cited page."},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}],"description":"A source domain, including its subdomains, such as g2.com.","title":"Domain"},"description":"A source domain, including its subdomains, such as g2.com."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Text to search for.","title":"Q"},"description":"Text to search for."},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"description":"Order results ascending or descending.","title":"Direction"},"description":"Order results ascending or descending."},{"name":"with_menus","in":"query","required":false,"schema":{"type":"boolean","description":"Include available filter choices.","default":false,"title":"With Menus"},"description":"Include available filter choices."},{"name":"sort","in":"query","required":false,"schema":{"enum":["title","citations","prompts"],"type":"string","description":"Field to order results by.","default":"citations","title":"Sort"},"description":"Field to order results by."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1CitedPages"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/cited-page":{"get":{"tags":["v1"],"summary":"Get Cited Page","description":"One cited page under the period and shared filters, daily answers included.\n\nUse its cited URL, canonical document key or document id as key. Prompts\nare paged; reports chart up to twelve weekly reports with the same filters.\nnames_you is null for your own pages or pages that have not been read.","operationId":"getCitedPage","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"key","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"The cited URL, canonical document key, or document id.","title":"Key"},"description":"The cited URL, canonical document key, or document id."},{"name":"prompts_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum related prompts to return.","default":10,"title":"Prompts Limit"},"description":"Maximum related prompts to return."},{"name":"prompts_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Related prompts to skip.","default":0,"title":"Prompts Offset"},"description":"Related prompts to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1CitedPage"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/ai-visits":{"get":{"tags":["v1"],"summary":"Get Ai Visits","description":"Owned pages ordered by citations over the selected period. Visits from AI\nuse the latest 28-day GA4 read, with its separate coverage dates. Counts\nare a floor and null without a complete dated read covering the page.","operationId":"listAiVisits","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1AiVisits"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/pages":{"get":{"tags":["v1"],"summary":"Get Pages","description":"The brand's own pages, most cited over the period first, with their\ncitations, Visits from AI, AI crawler hits and the stored rubric.\n\nVisits from AI read the bound GA4 property's 28-day read, with its own\ncoverage dates. AI crawler hits are frozen in the newest pinned weekly\nscan over crawler_hits_days whole days, 28 ending two days before it started.\nEach page's funnel uses that window for search, crawl, citation and visit\nmeasurements, with null for sources that did not measure the page.","operationId":"listPages","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["covered","weak","missing","unchecked","cited","falls_short","ranks_in_search","not_cited"],"type":"string"},{"type":"null"}],"description":"Filter by page status.","title":"Status"},"description":"Filter by page status."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Text to search for.","title":"Q"},"description":"Text to search for."},{"name":"sort","in":"query","required":false,"schema":{"enum":["topic","status","demand","citations","search_clicks","ai_visits","rank"],"type":"string","description":"Field to order results by.","default":"demand","title":"Sort"},"description":"Field to order results by."},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"description":"Order results ascending or descending.","title":"Direction"},"description":"Order results ascending or descending."},{"name":"with_menus","in":"query","required":false,"schema":{"type":"boolean","description":"Include available filter choices.","default":false,"title":"With Menus"},"description":"Include available filter choices."},{"name":"url","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"The page URL to select.","title":"Url"},"description":"The page URL to select."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Pages"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/pages/{page_id}":{"get":{"tags":["v1"],"summary":"Get Page","description":"One of the brand's own pages over the period: its citations and the\nprompts and answers that cite it, its weekly trend, the stored rubric with\neach pillar, AI crawler hits by bot and Visits from AI by assistant.\nThe funnel joins search, crawl, citation and visit measurements on the\nnewest pinned weekly scan's 28-day window, independent of period.\nwith_takes adds what AI took from the page: one take per prompt and\nengine, read from the evidence kept with each scan up to the pin.","operationId":"getPage","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"page_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A page id from the list.","title":"Page Id"},"description":"A page id from the list."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"with_details","in":"query","required":false,"schema":{"type":"boolean","description":"Include the page details.","default":false,"title":"With Details"},"description":"Include the page details."},{"name":"with_takes","in":"query","required":false,"schema":{"type":"boolean","description":"Include the page assessments.","default":false,"title":"With Takes"},"description":"Include the page assessments."},{"name":"takes_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum page assessments to return.","default":100,"title":"Takes Limit"},"description":"Maximum page assessments to return."},{"name":"takes_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Page assessments to skip.","default":0,"title":"Takes Offset"},"description":"Page assessments to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Page"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/content/write-language":{"get":{"tags":["v1"],"summary":"Get Content Language","description":"Preview a content order's write language without filing or charging it.\n\nOmit topic_key and document_id for a free Studio order. A missing topic\ntakes topic_key and segment; a page rewrite takes document_id.","operationId":"previewContentLanguage","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"topic_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":300},{"type":"null"}],"description":"Topic key.","title":"Topic Key"},"description":"Topic key."},{"name":"segment","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Topic segment label.","default":"default","title":"Segment"},"description":"Topic segment label."},{"name":"document_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Page document id.","title":"Document Id"},"description":"Page document id."},{"name":"page_url","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}],"description":"Page address.","title":"Page Url"},"description":"Page address."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentLanguagePreview"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/topics":{"get":{"tags":["v1"],"summary":"Get Topics","description":"Tracked topics with scores, AI bands, leaders and Cited share. Band filters\nand score sorts apply before paging. `view` also selects suggested or archived topics.","operationId":"listTopics","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"side","in":"query","required":false,"schema":{"enum":["all","ai","search"],"type":"string","description":"The side whose score orders a topic's `winners`. The `leader` uses Heralded Scores; `scores` always carries `all`, `ai` and `search`.","default":"all","title":"Side"},"description":"The side whose score orders a topic's `winners`. The `leader` uses Heralded Scores; `scores` always carries `all`, `ai` and `search`."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"with_trend","in":"query","required":false,"schema":{"type":"boolean","description":"Include weekly card figures and their adjacent-window changes.","default":false,"title":"With Trend"},"description":"Include weekly card figures and their adjacent-window changes."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Text to search for.","title":"Q"},"description":"Text to search for."},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"description":"Order results ascending or descending.","title":"Direction"},"description":"Order results ascending or descending."},{"name":"with_menus","in":"query","required":false,"schema":{"type":"boolean","description":"Include available filter choices.","default":false,"title":"With Menus"},"description":"Include available filter choices."},{"name":"url","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"The page URL to select.","title":"Url"},"description":"The page URL to select."},{"name":"band","in":"query","required":false,"schema":{"anyOf":[{"enum":["Invisible","Under-visible","Emerging","Strong","Leader","Not measured"],"type":"string"},{"type":"null"}],"description":"Filter by the topic score band.","title":"Band"},"description":"Filter by the topic score band."},{"name":"sort","in":"query","required":false,"schema":{"enum":["topic","demand","rank","ai_score","search_score","cited_pct"],"type":"string","description":"Field to order results by.","default":"demand","title":"Sort"},"description":"Field to order results by."},{"name":"view","in":"query","required":false,"schema":{"enum":["tracked","suggested","archived"],"type":"string","description":"tracked: the topics read now. suggested: needs Heralded found that the brand does not track. archived: archived topics.","default":"tracked","title":"View"},"description":"tracked: the topics read now. suggested: needs Heralded found that the brand does not track. archived: archived topics."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Topics"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/topics/{topic_id}":{"get":{"tags":["v1"],"summary":"Get Topic","description":"One topic's scores, own pages, question coverage, prompts, keywords,\nrivals, live actions and cited pages. `with_pane` adds its scores per engine,\nits Search trend, its keywords in Google's top 10, its brands and its page\ntotal. Take its id from topics, URL-encoded; a suggested topic's id is\n`s:{id}`.","operationId":"getTopic","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"topic_id","in":"path","required":true,"schema":{"type":"string","description":"Select a topic by id, or untagged for prompts without a topic.","title":"Topic Id"},"description":"Select a topic by id, or untagged for prompts without a topic."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"side","in":"query","required":false,"schema":{"enum":["all","ai","search"],"type":"string","description":"The side whose score orders a topic's `winners`. The `leader` uses Heralded Scores; `scores` always carries `all`, `ai` and `search`.","default":"all","title":"Side"},"description":"The side whose score orders a topic's `winners`. The `leader` uses Heralded Scores; `scores` always carries `all`, `ai` and `search`."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"preview","in":"query","required":false,"schema":{"type":"boolean","description":"Return bounded section previews.","default":false,"title":"Preview"},"description":"Return bounded section previews."},{"name":"section","in":"query","required":false,"schema":{"anyOf":[{"enum":["questions","unanswered","own_pages","pages","brands","segments","engines","keywords","work"],"type":"string"},{"type":"null"}],"description":"The section paged by limit and offset.","title":"Section"},"description":"The section paged by limit and offset."},{"name":"with_pane","in":"query","required":false,"schema":{"type":"boolean","description":"Add the topic's scores per engine, its Mentioned and Recommended answer counts, its Search trend, its keywords in Google's top 10, its brands and its page total, as `by_engine`, `ai_counts`, `search_trend`, `keywords_top10`, `brands`, `brands_total` and `pages_total`.","default":false,"title":"With Pane"},"description":"Add the topic's scores per engine, its Mentioned and Recommended answer counts, its Search trend, its keywords in Google's top 10, its brands and its page total, as `by_engine`, `ai_counts`, `search_trend`, `keywords_top10`, `brands`, `brands_total` and `pages_total`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1TopicDetail"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/products":{"get":{"tags":["v1"],"summary":"Get Products","description":"An ecommerce brand's products in AI shopping answers: the period's product card\nfigures, complete product data and revenue from AI, and a page of its products with\nhow often each was shown, its place, the price and seller shown and its product\ndata. Its catalogue's products are listed at zero when never shown.","operationId":"listProducts","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Check country or global. Omit for all.","title":"Country"},"description":"Check country or global. Omit for all."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"view","in":"query","required":false,"schema":{"enum":["yours","competitors","all"],"type":"string","description":"Your products, tracked competitors' products, or all observed products.","default":"yours","title":"View"},"description":"Your products, tracked competitors' products, or all observed products."},{"name":"maker","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"description":"Canonical maker key.","title":"Maker"},"description":"Canonical maker key."},{"name":"competitor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"description":"Tracked competitor key.","title":"Competitor"},"description":"Tracked competitor key."},{"name":"with_makers","in":"query","required":false,"schema":{"type":"boolean","description":"Include canonical maker filter options.","default":false,"title":"With Makers"},"description":"Include canonical maker filter options."},{"name":"makers_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum maker options (100).","default":20,"title":"Makers Limit"},"description":"Maximum maker options (100)."},{"name":"makers_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Maker options to skip.","default":0,"title":"Makers Offset"},"description":"Maker options to skip."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Text to search for.","title":"Q"},"description":"Text to search for."},{"name":"shown","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Keep products shown in an organic product card in the period, or products not shown when false.","title":"Shown"},"description":"Keep products shown in an organic product card in the period, or products not shown when false."},{"name":"sort","in":"query","required":false,"schema":{"enum":["shown","position","revenue","title","readiness"],"type":"string","description":"Field to order results by.","default":"shown","title":"Sort"},"description":"Field to order results by."},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"description":"Order results ascending or descending.","title":"Direction"},"description":"Order results ascending or descending."},{"name":"revenue_pages_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Landing pages of revenue from AI per page (100).","default":10,"title":"Revenue Pages Limit"},"description":"Landing pages of revenue from AI per page (100)."},{"name":"revenue_pages_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Landing pages of revenue from AI to skip.","default":0,"title":"Revenue Pages Offset"},"description":"Landing pages of revenue from AI to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Products"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/products/sellers":{"get":{"tags":["v1"],"summary":"Get Product Sellers","description":"The sellers the period's product cards showed, with how many product appearances\neach sold and how many of them were your products.","operationId":"listProductSellers","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Check country or global. Omit for all.","title":"Country"},"description":"Check country or global. Omit for all."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"sort","in":"query","required":false,"schema":{"enum":["shown","yours","title"],"type":"string","description":"Field to order results by.","default":"shown","title":"Sort"},"description":"Field to order results by."},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"description":"Order results ascending or descending.","title":"Direction"},"description":"Order results ascending or descending."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ProductSellers"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/products/google-shopping":{"get":{"tags":["v1"],"summary":"Get Google Shopping","description":"Your best organic Google Shopping position for each search the newest report in\nthe period read, or its absence from the products read, beside the page's first\nproduct.","operationId":"listGoogleShoppingSearches","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"sort","in":"query","required":false,"schema":{"enum":["volume","position","title"],"type":"string","description":"Field to order results by.","default":"volume","title":"Sort"},"description":"Field to order results by."},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"description":"Order results ascending or descending.","title":"Direction"},"description":"Order results ascending or descending."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1GoogleShopping"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/products/readiness":{"get":{"tags":["v1"],"summary":"Get Product Readiness","description":"How the product pages checked in the newest catalogue read in the period meet\nGoogle's and OpenAI's product data standards: its outcome, complete product data,\nthe four stages and every check that applied and could run.","operationId":"listProductReadinessChecks","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ProductReadiness"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/products/{product_id}":{"get":{"tags":["v1"],"summary":"Get Product","description":"One product, yours or one shown instead: its figures, trend, engines, the\nquestions it was shown on or missed, the products shown instead, what answers state\nabout it, the pages they cite, its product data, revenue from AI and the work on its\npage.","operationId":"getProduct","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"product_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A product id from listProducts.","title":"Product Id"},"description":"A product id from listProducts."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Check country or global. Omit for all.","title":"Country"},"description":"Check country or global. Omit for all."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"questions_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Questions per page (100).","default":10,"title":"Questions Limit"},"description":"Questions per page (100)."},{"name":"questions_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Questions to skip.","default":0,"title":"Questions Offset"},"description":"Questions to skip."},{"name":"instead_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Products shown instead per page (100).","default":10,"title":"Instead Limit"},"description":"Products shown instead per page (100)."},{"name":"instead_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Products shown instead to skip.","default":0,"title":"Instead Offset"},"description":"Products shown instead to skip."},{"name":"sources_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Cited pages per page (100).","default":10,"title":"Sources Limit"},"description":"Cited pages per page (100)."},{"name":"sources_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Cited pages to skip.","default":0,"title":"Sources Offset"},"description":"Cited pages to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ProductDetail"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/keywords":{"get":{"tags":["v1"],"summary":"Get Keywords","description":"The brand's keywords: how buyers search Google for each topic, in each segment,\nwith the monthly searches, your best rank, the results that name you and the\nkeyword's score. `view` picks tracked or archived keywords.","operationId":"listKeywords","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Check country or global. Omit for all.","title":"Country"},"description":"Check country or global. Omit for all."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"group","in":"query","required":false,"schema":{"anyOf":[{"enum":["concept","market","topic"],"type":"string"},{"type":"null"}],"description":"concept: a row per English gloss across topics and markets; market: a row per market; topic: a row per topic with its own keyword and market members.","title":"Group"},"description":"concept: a row per English gloss across topics and markets; market: a row per market; topic: a row per topic with its own keyword and market members."},{"name":"position","in":"query","required":false,"schema":{"anyOf":[{"enum":["top_3","top_10","not_in_top_10","unchecked"],"type":"string"},{"type":"null"}],"description":"Latest fetched rank; unchecked if none.","title":"Position"},"description":"Latest fetched rank; unchecked if none."},{"name":"ai_overview","in":"query","required":false,"schema":{"anyOf":[{"enum":["cites_you","cites_others","none"],"type":"string"},{"type":"null"}],"description":"Latest AI Overview.","title":"Ai Overview"},"description":"Latest AI Overview."},{"name":"mentions","in":"query","required":false,"schema":{"anyOf":[{"enum":["mentioned","recommended"],"type":"string"},{"type":"null"}],"description":"Latest check mentions or recommends you.","title":"Mentions"},"description":"Latest check mentions or recommends you."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"description":"Substring of text, gloss or market.","title":"Q"},"description":"Substring of text, gloss or market."},{"name":"with_summary","in":"query","required":false,"schema":{"type":"boolean","description":"Include a Search summary.","default":false,"title":"With Summary"},"description":"Include a Search summary."},{"name":"view","in":"query","required":false,"schema":{"enum":["tracked","archived"],"type":"string","description":"tracked or archived.","default":"tracked","title":"View"},"description":"tracked or archived."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Topic filter; group=concept keeps concepts with a member in it.","title":"Topic"},"description":"Topic filter; group=concept keeps concepts with a member in it."},{"name":"sort","in":"query","required":false,"schema":{"enum":["searches","keyword","best_rank","clicks","score","markets_top10","change"],"type":"string","description":"Sort; nulls last.","default":"searches","title":"Sort"},"description":"Sort; nulls last."},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"description":"desc; keyword asc.","title":"Direction"},"description":"desc; keyword asc."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Keywords"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/keywords/{keyword_id}":{"get":{"tags":["v1"],"summary":"Get Keyword","description":"One keyword: its figures over the period with their range, your best rank at each\nweekly report, the top 10 of the latest check, the prompts that make AI search it and\nthe tasks about your pages.","operationId":"getKeyword","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"keyword_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A keyword id from the list.","title":"Keyword Id"},"description":"A keyword id from the list."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"preview","in":"query","required":false,"schema":{"type":"boolean","description":"Return bounded section previews and market choices.","default":false,"title":"Preview"},"description":"Return bounded section previews and market choices."},{"name":"section","in":"query","required":false,"schema":{"anyOf":[{"enum":["questions","results","work"],"type":"string"},{"type":"null"}],"description":"The section paged by limit and offset.","title":"Section"},"description":"The section paged by limit and offset."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1KeywordDetail"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/audit":{"get":{"tags":["v1"],"summary":"Get Audit","description":"The latest crawl's readiness, site checks by group and pages.\n\nAudit has no period. Page citations count the last weekly scan, named in\ncitations_scan. AI crawls use the same frozen 28-day window as page reads,\nending two days before that weekly scan started.","operationId":"getAudit","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"finding","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"A finding id whose pages start at finding_pages_offset.","title":"Finding"},"description":"A finding id whose pages start at finding_pages_offset."},{"name":"finding_pages_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"The pages listed under each finding.","default":10,"title":"Finding Pages Limit"},"description":"The pages listed under each finding."},{"name":"finding_pages_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages to skip within the selected finding.","default":0,"title":"Finding Pages Offset"},"description":"Pages to skip within the selected finding."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"A name from facets.","title":"Category"},"description":"A name from facets."},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":35},{"type":"null"}],"description":"A code from facets.","title":"Language"},"description":"A code from facets."},{"name":"findings","in":"query","required":false,"schema":{"anyOf":[{"enum":["issue","improve","none"],"type":"string"},{"type":"null"}],"description":"issue: holds an issue; improve: holds improvements and no issue; none: holds neither.","title":"Findings"},"description":"issue: holds an issue; improve: holds improvements and no issue; none: holds neither."},{"name":"access","in":"query","required":false,"schema":{"anyOf":[{"enum":["readable","blocked","unmeasured"],"type":"string"},{"type":"null"}],"description":"Whether AI engines can read the page: readable, blocked by any cause status names, or unmeasured (not_read).","title":"Access"},"description":"Whether AI engines can read the page: readable, blocked by any cause status names, or unmeasured (not_read)."},{"name":"changed","in":"query","required":false,"schema":{"anyOf":[{"enum":["new","changed"],"type":"string"},{"type":"null"}],"description":"Found, or its content changed, since the previous weekly read.","title":"Changed"},"description":"Found, or its content changed, since the previous weekly read."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["readable","blocked_robots","noindex","does_not_load","needs_javascript","not_read"],"type":"string"},{"type":"null"}],"description":"Filter by page status.","title":"Status"},"description":"Filter by page status."},{"name":"cited","in":"query","required":false,"schema":{"anyOf":[{"enum":["cited","not_cited"],"type":"string"},{"type":"null"}],"description":"Filter pages by citation state.","title":"Cited"},"description":"Filter pages by citation state."},{"name":"page_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["product","product_detail","collection","solution","pricing","blog_post","customer_story","press","documentation","resource","comparison","legal","home","about","contact","careers","landing","blog_index","utility","other"],"type":"string"},{"type":"null"}],"description":"Filter by page type.","title":"Page Type"},"description":"Filter by page type."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Text to search for.","title":"Q"},"description":"Text to search for."},{"name":"sort","in":"query","required":false,"schema":{"enum":["citations","page","status","crawls","read","findings","clicks"],"type":"string","description":"Field to order results by.","default":"citations","title":"Sort"},"description":"Field to order results by."},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"description":"Order results ascending or descending.","title":"Direction"},"description":"Order results ascending or descending."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"check","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"A website check key to read.","title":"Check"},"description":"A website check key to read."},{"name":"checks_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum website checks to return.","default":10,"title":"Checks Limit"},"description":"Maximum website checks to return."},{"name":"checks_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Website checks to skip.","default":0,"title":"Checks Offset"},"description":"Website checks to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Audit"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/audit/competitors":{"get":{"tags":["v1"],"summary":"Get Audit Competitors","description":"The frozen weekly competitor table, homepages and paged changes feed.\ncompetitor filters changes by key, and change selects their type.","operationId":"listAuditCompetitors","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"competitor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":300},{"type":"null"}],"description":"Filter by competitor key.","title":"Competitor"},"description":"Filter by competitor key."},{"name":"change","in":"query","required":false,"schema":{"anyOf":[{"enum":["new_page","removed_page","homepage_changed","pricing_changed","key_page_changed"],"type":"string"},{"type":"null"}],"description":"Filter by website change type.","title":"Change"},"description":"Filter by website change type."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1CompetitorSites"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/audit/competitors/{key}":{"get":{"tags":["v1"],"summary":"Get Audit Competitor","description":"One competitor's homepage, pricing, categories, weekly activity and changes.","operationId":"getAuditCompetitor","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"key","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":300,"description":"A competitor key from list_competitors.","title":"Key"},"description":"A competitor key from list_competitors."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"competitor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":300},{"type":"null"}],"description":"Filter by competitor key.","title":"Competitor"},"description":"Filter by competitor key."},{"name":"change","in":"query","required":false,"schema":{"anyOf":[{"enum":["new_page","removed_page","homepage_changed","pricing_changed","key_page_changed"],"type":"string"},{"type":"null"}],"description":"Filter by website change type.","title":"Change"},"description":"Filter by website change type."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1CompetitorSiteDetail"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/website/scope":{"get":{"tags":["v1"],"summary":"Get Site Scope","description":"Current host and section states, discovery signals and decision provenance.","operationId":"getSiteScope","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SiteScope"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/audit/map":{"get":{"tags":["v1"],"summary":"Get Audit Map","description":"The site map frozen with the run the brand's Website read serves, named in\nmeta.data_as_of: every page in one language with the links between them and what\neach holds back, or one folder of it.","operationId":"getAuditMap","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"page","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"A page URL whose language to open when language is unset.","title":"Page"},"description":"A page URL whose language to open when language is unset."},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":35},{"type":"null"}],"description":"A code from languages; default the site's primary language.","title":"Language"},"description":"A code from languages; default the site's primary language."},{"name":"folder","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"A path such as /blog: its own pages and the folders under it, in place of every page. / is the top of the site.","title":"Folder"},"description":"A path such as /blog: its own pages and the folders under it, in place of every page. / is the top of the site."},{"name":"folder_pages_limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"The folder's pages listed, with folder.","default":50,"title":"Folder Pages Limit"},"description":"The folder's pages listed, with folder."},{"name":"folder_pages_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages to skip within the folder.","default":0,"title":"Folder Pages Offset"},"description":"Pages to skip within the folder."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SiteMap"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/audit/pages":{"get":{"tags":["v1"],"summary":"Get Audit Pages","description":"The latest crawl's pages under filters, each with its category, language, the findings\nholding it back, the brief's claims it states and whether it is new or changed since the\nprevious weekly read, as the run the Website read serves froze them (meta.data_as_of).\n`facets` counts each category under every filter but `category`, so a chip's count is\nthe total with that chip chosen, and each language under every filter. The same pages,\nunfiltered, are `GET .../audit`'s `pages`.","operationId":"listAuditPages","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"A name from facets.","title":"Category"},"description":"A name from facets."},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":35},{"type":"null"}],"description":"A code from facets.","title":"Language"},"description":"A code from facets."},{"name":"findings","in":"query","required":false,"schema":{"anyOf":[{"enum":["issue","improve","none"],"type":"string"},{"type":"null"}],"description":"issue: holds an issue; improve: holds improvements and no issue; none: holds neither.","title":"Findings"},"description":"issue: holds an issue; improve: holds improvements and no issue; none: holds neither."},{"name":"access","in":"query","required":false,"schema":{"anyOf":[{"enum":["readable","blocked","unmeasured"],"type":"string"},{"type":"null"}],"description":"Whether AI engines can read the page: readable, blocked by any cause status names, or unmeasured (not_read).","title":"Access"},"description":"Whether AI engines can read the page: readable, blocked by any cause status names, or unmeasured (not_read)."},{"name":"changed","in":"query","required":false,"schema":{"anyOf":[{"enum":["new","changed"],"type":"string"},{"type":"null"}],"description":"Found, or its content changed, since the previous weekly read.","title":"Changed"},"description":"Found, or its content changed, since the previous weekly read."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["readable","blocked_robots","noindex","does_not_load","needs_javascript","not_read"],"type":"string"},{"type":"null"}],"description":"Filter by page status.","title":"Status"},"description":"Filter by page status."},{"name":"cited","in":"query","required":false,"schema":{"anyOf":[{"enum":["cited","not_cited"],"type":"string"},{"type":"null"}],"description":"Filter pages by citation state.","title":"Cited"},"description":"Filter pages by citation state."},{"name":"page_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["product","product_detail","collection","solution","pricing","blog_post","customer_story","press","documentation","resource","comparison","legal","home","about","contact","careers","landing","blog_index","utility","other"],"type":"string"},{"type":"null"}],"description":"Filter by page type.","title":"Page Type"},"description":"Filter by page type."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Text to search for.","title":"Q"},"description":"Text to search for."},{"name":"sort","in":"query","required":false,"schema":{"enum":["citations","page","status","crawls","read","findings","clicks"],"type":"string","description":"Field to order results by.","default":"citations","title":"Sort"},"description":"Field to order results by."},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"description":"Order results ascending or descending.","title":"Direction"},"description":"Order results ascending or descending."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SitePages"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/audit/key-pages":{"get":{"tags":["v1"],"summary":"Get Audit Key Pages","description":"The key pages of the run the Website read serves, named in meta.data_as_of: each\npage's above-the-fold read with its screenshot, what changed in that read, the last four\nweeks as a strip and its history. `summary` counts the key pages that changed since the\nprevious weekly read.","operationId":"listAuditKeyPages","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1KeyPages"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/audit/key-pages/{path}":{"get":{"tags":["v1"],"summary":"Get Audit Key Page","description":"One key page, by its path without the leading slash; the homepage is the empty\npath. A page that is not a key page of that run is `not_found`.","operationId":"getAuditKeyPage","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"path","in":"path","required":true,"schema":{"type":"string","description":"A key page path, such as /pricing.","title":"Path"},"description":"A key page path, such as /pricing."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1KeyPageDetail"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/perception":{"get":{"tags":["v1"],"summary":"Get Perception","description":"The statement, positioning, claims, negative prompts and sources, and best quotes.","operationId":"getPerception","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"list_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"description":"Maximum rows in each supporting list.","title":"List Limit"},"description":"Maximum rows in each supporting list."},{"name":"prompts_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Related prompts to skip.","default":0,"title":"Prompts Offset"},"description":"Related prompts to skip."},{"name":"sources_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Sources to skip.","default":0,"title":"Sources Offset"},"description":"Sources to skip."},{"name":"pages_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages or opinion holders to skip.","default":0,"title":"Pages Offset"},"description":"Pages or opinion holders to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Perception"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/moving-away-from":{"get":{"tags":["v1"],"summary":"Get Moving Away From","description":"For each label the brand is moving away from, the share of answers naming it that still\ndescribe it that way, the change against the baseline where the paired test calls it real,\nthe newest answer's words, and the cited pages that repeat it.","operationId":"getMovingAwayFrom","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"label","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":40},{"type":"null"}],"description":"One label's key from the labels list, for that label alone.","title":"Label"},"description":"One label's key from the labels list, for that label alone."},{"name":"list_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum pages listed under each label.","default":10,"title":"List Limit"},"description":"Maximum pages listed under each label."},{"name":"pages_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages to skip under each label.","default":0,"title":"Pages Offset"},"description":"Pages to skip under each label."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1MovingAwayFrom"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/perception/claims/{claim}":{"get":{"tags":["v1"],"summary":"Get Perception Claim","description":"One claim's verdicts, quotes, contradicting prompts, engines and pages.","operationId":"getPerceptionClaim","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"claim","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":300,"description":"A claim key from the claims list.","title":"Claim"},"description":"A claim key from the claims list."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"list_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"description":"Maximum rows in each supporting list.","title":"List Limit"},"description":"Maximum rows in each supporting list."},{"name":"prompts_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Related prompts to skip.","default":0,"title":"Prompts Offset"},"description":"Related prompts to skip."},{"name":"sources_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Sources to skip.","default":0,"title":"Sources Offset"},"description":"Sources to skip."},{"name":"pages_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages or opinion holders to skip.","default":0,"title":"Pages Offset"},"description":"Pages or opinion holders to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1PerceptionClaim"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/reputation":{"get":{"tags":["v1"],"summary":"Get Reputation","description":"Understood and Praised from AI answers and the web, the facts with what the web says\nof each, negative prompts and sources, and best quotes.","operationId":"getReputation","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"list_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"description":"Maximum rows in each supporting list.","title":"List Limit"},"description":"Maximum rows in each supporting list."},{"name":"prompts_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Related prompts to skip.","default":0,"title":"Prompts Offset"},"description":"Related prompts to skip."},{"name":"sources_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Sources to skip.","default":0,"title":"Sources Offset"},"description":"Sources to skip."},{"name":"pages_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages or opinion holders to skip.","default":0,"title":"Pages Offset"},"description":"Pages or opinion holders to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Reputation"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/reputation/claims/{claim}":{"get":{"tags":["v1"],"summary":"Get Reputation Claim","description":"One fact's AI verdicts, quotes, contradicting prompts, engines and pages, and the\npages elsewhere that agree or contradict it.","operationId":"getReputationClaim","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"claim","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":300,"description":"A claim key from the claims list.","title":"Claim"},"description":"A claim key from the claims list."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"list_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"description":"Maximum rows in each supporting list.","title":"List Limit"},"description":"Maximum rows in each supporting list."},{"name":"prompts_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Related prompts to skip.","default":0,"title":"Prompts Offset"},"description":"Related prompts to skip."},{"name":"sources_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Sources to skip.","default":0,"title":"Sources Offset"},"description":"Sources to skip."},{"name":"pages_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages or opinion holders to skip.","default":0,"title":"Pages Offset"},"description":"Pages or opinion holders to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ReputationClaim"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/reviews":{"get":{"tags":["v1"],"summary":"Get Reviews","description":"The brand's review ratings by platform and newest reviews.","operationId":"listReviews","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Reviews"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/reviews/{review_id}":{"get":{"tags":["v1"],"summary":"Get Review","description":"One review and whether its reply has been recorded.","operationId":"getReview","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"review_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A review id from the list; omit to list reviews.","title":"Review Id"},"description":"A review id from the list; omit to list reviews."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Review"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/reputation/opinions/{opinion_id}":{"get":{"tags":["v1"],"summary":"Get Reputation Opinion","description":"One opinion with its holders: the AI answers, threads, posts and pages that state it,\nwith the passage of each.","operationId":"getReputationOpinion","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"opinion_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"An opinion id from the opinions list.","title":"Opinion Id"},"description":"An opinion id from the opinions list."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all.","title":"Market"},"description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"all_buyers","type":"string"},{"type":"null"}],"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all.","title":"Audience"},"description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},{"name":"engine","in":"query","required":false,"schema":{"anyOf":[{"enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"type":"string"},{"type":"null"}],"description":"Answering AI engine.","title":"Engine"},"description":"Answering AI engine."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["organic","brand_specific","competitor_comparison"],"type":"string"},{"type":"null"}],"description":"Question type.","title":"Type"},"description":"Question type."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"enum":["educational","problem","comparison","transactional"],"type":"string"},{"type":"null"}],"description":"Question intent.","title":"Intent"},"description":"Question intent."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Tracked topic UUID.","title":"Topic"},"description":"Tracked topic UUID."},{"name":"prompt","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Question id from list_prompts.","title":"Prompt"},"description":"Question id from list_prompts."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"period","in":"query","required":false,"schema":{"enum":["1w","4w","12w","all"],"type":"string","description":"Weekly-report period.","default":"1w","title":"Period"},"description":"Weekly-report period."},{"name":"list_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"description":"Maximum rows in each supporting list.","title":"List Limit"},"description":"Maximum rows in each supporting list."},{"name":"prompts_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Related prompts to skip.","default":0,"title":"Prompts Offset"},"description":"Related prompts to skip."},{"name":"sources_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Sources to skip.","default":0,"title":"Sources Offset"},"description":"Sources to skip."},{"name":"pages_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages or opinion holders to skip.","default":0,"title":"Pages Offset"},"description":"Pages or opinion holders to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ReputationOpinionPane"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/evidence":{"get":{"tags":["v1"],"summary":"Get Evidence","description":"The latest available weekly report evidence and the plays its owners offer.","operationId":"listEvidence","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"subject","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512,"pattern":"^(prompt|topic|keyword|figure|source|competitor|engine|page):.+$"},{"type":"null"}],"description":"Keep evidence about `prompt:<uid>`, `topic:<id>`, `keyword:<id>`, `figure:<axis>`, `source:<domain>` or `competitor:<key>`. Figures match the measure named by the work this evidence supports. Evidence without a matching measure is excluded.","title":"Subject"},"description":"Keep evidence about `prompt:<uid>`, `topic:<id>`, `keyword:<id>`, `figure:<axis>`, `source:<domain>` or `competitor:<key>`. Figures match the measure named by the work this evidence supports. Evidence without a matching measure is excluded."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Evidence"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/actions":{"get":{"tags":["v1"],"summary":"Get Actions","description":"Proposed actions (group new) come as this week's (above the floor, at most two of one\nplay), then the backlog, each in the brand's order then by priority; other groups newest\nfirst. With assignee=mine_or_open, your_input is oldest-waiting first and includes\nstopped site checks. Dispatchers see their own work and work with no dispatching owner;\nreaders without dispatch and service tokens see all work. waiting_since dates the ask.\nEach carries its grounds, gain band, done-when and what Heralded tracks.","operationId":"listActions","security":[{"serviceToken":[]},{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"group","in":"query","required":false,"schema":{"anyOf":[{"enum":["new","your_input","dispatched","scheduled","waiting","settled","withdrawn"],"type":"string"},{"type":"null"}],"description":"Select an action work group.","title":"Group"},"description":"Select an action work group."},{"name":"assignee","in":"query","required":false,"schema":{"anyOf":[{"enum":["me","heralded","mine_or_open"],"type":"string"},{"type":"null"}],"description":"me selects actions assigned to you; heralded selects actions with no person assigned. mine_or_open selects your own and unassigned work, including work whose owner cannot start work. Readers without permission to start work and service tokens see everyone. Omit for anyone.","title":"Assignee"},"description":"me selects actions assigned to you; heralded selects actions with no person assigned. mine_or_open selects your own and unassigned work, including work whose owner cannot start work. Readers without permission to start work and service tokens see everyone. Omit for anyone."},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Actions targeting this topic, its prompts or its pages.","title":"Topic"},"description":"Actions targeting this topic, its prompts or its pages."},{"name":"subject","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512,"pattern":"^(prompt|topic|keyword|figure|source|competitor|engine|page):.+$"},{"type":"null"}],"description":"Keep the live actions about one subject: `prompt:<uid>`, `topic:<id>`, `keyword:<id>`, `figure:<axis>`, `source:<domain>`, `competitor:<key>`, `engine:<id>` or `page:<url>`. A subject the brand does not have matches nothing.","title":"Subject"},"description":"Keep the live actions about one subject: `prompt:<uid>`, `topic:<id>`, `keyword:<id>`, `figure:<axis>`, `source:<domain>`, `competitor:<key>`, `engine:<id>` or `page:<url>`. A subject the brand does not have matches nothing."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Actions"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}}}}},"/v1/brands/{brand_id}/assets":{"get":{"tags":["v1"],"summary":"Get Assets","description":"Current assets, filtered by type, lifecycle state and owner before cursor paging.\n\nEach asset names its action. Older versions remain on that action's full page.","operationId":"listAssets","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"description":"Asset type from the returned types.","title":"Type"},"description":"Asset type from the returned types."},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"enum":["drafting","review","approved","live","stopped","failed"],"type":"string"},{"enum":["ready","verifying"],"type":"string"},{"type":"null"}],"description":"Asset lifecycle group.","title":"State"},"description":"Asset lifecycle group."},{"name":"owner","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"const":"unassigned","type":"string"},{"type":"null"}],"description":"Owner account id, or unassigned.","title":"Owner"},"description":"Owner account id, or unassigned."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Assets"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/results":{"get":{"tags":["v1"],"summary":"Get Results","description":"Delivered actions with ordered steps for their kind, citations and measured outcomes.\n\nCounts cover all delivered rows. Order by label or newest result, and use next_cursor\nfor the next page. Setup, prompt additions and deliveries undone by reopening are excluded.","operationId":"listResults","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"order","in":"query","required":false,"schema":{"enum":["label","newest"],"type":"string","description":"label orders Paying off, Cited, then Delivered; newest orders by result date.","default":"label","title":"Order"},"description":"label orders Paying off, Cited, then Delivered; newest orders by result date."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Results"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/herald":{"get":{"tags":["v1"],"summary":"Get Herald Greeting","description":"The Herald's opening greeting and page questions, with no model call or answer charge.\n\nCounts reuse the brand's current work and delivered-results populations;\nnew results are compared with the caller's last recorded Home visit.","operationId":"getHeraldGreeting","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"page","in":"query","required":false,"schema":{"enum":["home","work","reports","strategy","visibility","competitors","perception","website","sources","answers"],"type":"string","description":"The page from which the Herald is opened.","default":"home","title":"Page"},"description":"The page from which the Herald is opened."},{"name":"scope","in":"query","required":false,"schema":{"type":"string","maxLength":4096,"description":"Active page filters as a URL query string, without the leading question mark.","default":"","title":"Scope"},"description":"Active page filters as a URL query string, without the leading question mark."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HeraldGreeting"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/conversations":{"get":{"tags":["v1"],"summary":"List Conversations","description":"Standing threads, shared chats and your own private chats, including archived chats.\nOwners and admins cannot read others' private chats.","operationId":"listConversations","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationList"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/conversations/{conversation_id}/messages":{"get":{"tags":["v1"],"summary":"Get Conversation By Id","description":"One visible conversation's messages, newest first. Pass next_cursor as cursor to\ncontinue. Posting and confirming stay in the app. A hidden conversation returns 404.","operationId":"listConversationMessages","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A conversation id from list_conversations.","title":"Conversation Id"},"description":"A conversation id from list_conversations."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":50,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ConversationPage"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/conversations/{member}":{"get":{"tags":["v1"],"summary":"Get Conversation","description":"Historical messages in a shared conversation, newest first.\nFilter by task_id and pass next_cursor as cursor to continue.\nPosting and suggestion clicks stay in the app.","operationId":"getConversation","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"member","in":"path","required":true,"schema":{"enum":["writer","publicist","engineer"],"type":"string","description":"The stored conversation key whose history to read.","title":"Member"},"description":"The stored conversation key whose history to read."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":50,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"task_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Read the conversation for this action id.","title":"Task Id"},"description":"Read the conversation for this action id."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Conversation"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/actions/{action_id}":{"get":{"tags":["v1"],"summary":"Get Action","description":"One action as its pane reads it: state, verbs, job, costs, assignee, steps, thread,\ndraft versions, application, the scans that raised it and evidence, with its grounds,\ndone-when, what Heralded tracks and the trail of what happened since delivery. `as_of`\npins the evidence to a scan; the work itself is live.","operationId":"getAction","security":[{"apiKey":[]}],"parameters":[{"name":"action_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"An action id from list_actions.","title":"Action Id"},"description":"An action id from list_actions."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Section page size, at most 100.","default":5,"title":"Limit"},"description":"Section page size, at most 100."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"with_details","in":"query","required":false,"schema":{"type":"boolean","description":"Include all sections; false returns a compact preview.","default":true,"title":"With Details"},"description":"Include all sections; false returns a compact preview."},{"name":"with_viewer","in":"query","required":false,"schema":{"type":"boolean","description":"Include the caller's visible activity names, kit, rewrite allowance and whether the work is assigned to them.","default":false,"title":"With Viewer"},"description":"Include the caller's visible activity names, kit, rewrite allowance and whether the work is assigned to them."},{"name":"section","in":"query","required":false,"schema":{"anyOf":[{"enum":["activity","pages","targets","versions","evidence","sources","emails"],"type":"string"},{"type":"null"}],"description":"Read one paged section instead of all detail.","title":"Section"},"description":"Read one paged section instead of all detail."},{"name":"step","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"description":"With `section=activity`, page only the events of this step, by its `key`.","title":"Step"},"description":"With `section=activity`, page only the events of this step, by its `key`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ActionDetail"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/actions/{action_id}/piece/images/{slot}":{"get":{"tags":["v1"],"summary":"Get Action Piece Image","description":"Download the selected image for a piece. Returns a 307 redirect to a fresh\nsigned file URL. The redirect is cacheable privately for 10 minutes.","operationId":"getActionPieceImage","security":[{"apiKey":[]}],"parameters":[{"name":"action_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The action whose piece image to download.","title":"Action Id"},"description":"The action whose piece image to download."},{"name":"slot","in":"path","required":true,"schema":{"enum":["featured","social"],"type":"string","description":"Featured image or social preview.","title":"Slot"},"description":"Featured image or social preview."}],"responses":{"307":{"description":"Successful Response"},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/work":{"get":{"tags":["v1"],"summary":"Get Work","description":"The team's live jobs, next daily or weekly scan and completed-work tallies.","operationId":"getWork","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Work"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/reports":{"get":{"tags":["v1"],"summary":"List Reports","description":"The brand's weekly and quarterly reports, newest first, including those\nissued for a site it tracked before. A report never changes once issued.","operationId":"listReports","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"enum":["weekly","quarterly"],"type":"string"},{"type":"null"}],"description":"weekly or quarterly; omit for both.","title":"Kind"},"description":"weekly or quarterly; omit for both."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportEditions"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/reports/{report_id}":{"get":{"tags":["v1"],"summary":"Get Report","description":"One report as it issued: where the brand stood in AI answers and Google\nsearch, what moved, work completed, competitors and the open work at issue.\nA section the report had no data for stays missing.","operationId":"getReport","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"report_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A report id from listReports.","title":"Report Id"},"description":"A report id from listReports."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportEditionRead"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/reports/{report_id}/recipients":{"get":{"tags":["v1"],"summary":"List Report Recipients","description":"Who a report was sent to, newest send first.","operationId":"listReportRecipients","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"report_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A report id from listReports.","title":"Report Id"},"description":"A report id from listReports."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditionRecipients"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/look":{"get":{"tags":["v1"],"summary":"Get Brand Look","description":"The brand's colours, fonts, logos and social card style, without image URLs.","operationId":"getBrandLook","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandLookRead"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/look/images/{slot}":{"get":{"tags":["v1"],"summary":"Download Brand Look Image","description":"Download a logo or social style card through a private, ten-minute redirect.","operationId":"getBrandLookImage","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"slot","in":"path","required":true,"schema":{"enum":["logo","logo_dark","mounted","strip","band"],"type":"string","description":"The logo or social card layout to download.","title":"Slot"},"description":"The logo or social card layout to download."}],"responses":{"307":{"description":"Successful Response"},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/strategy":{"get":{"tags":["v1"],"summary":"Get Strategy","description":"The goal with its revisions, baseline, current figures and target, the focus stars and\nthe labels the brand is moving away from. Recommended, Mentioned and Understood are read\non the goal's own questions; nothing compares across revisions.","operationId":"getStrategy","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategyRead"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/weekly-brief":{"get":{"tags":["v1"],"summary":"Get Weekly Brief","description":"The issued decisions for this reader, their completion, and new arrivals separately.","operationId":"listWeeklyBrief","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"with_today","in":"query","required":false,"schema":{"type":"boolean","description":"Include the viewer's live Today box alongside the issued brief.","default":false,"title":"With Today"},"description":"Include the viewer's live Today box alongside the issued brief."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WeeklyBrief"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/week-timeline":{"get":{"tags":["v1"],"summary":"Get Week Timeline","description":"The week's observed changes, results linked to work, and competitor moves.","operationId":"listWeekTimeline","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"week","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Monday starting the week; omit for this week.","title":"Week"},"description":"Monday starting the week; omit for this week."},{"name":"day","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"UTC day within the selected week; pages rows in lead order.","title":"Day"},"description":"UTC day within the selected week; pages rows in lead order."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WeekTimeline"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/focus-cards":{"get":{"tags":["v1"],"summary":"Get Focus Cards","description":"Two served figures for each starred focus.","operationId":"getFocusCards","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusCards"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/settings":{"get":{"tags":["v1"],"summary":"Get Brand Settings","description":"Current profile, rivals, owned domains, autonomy, connection status.","operationId":"getBrandSettings","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Settings"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/markets":{"get":{"tags":["v1"],"summary":"Get Brand Markets","description":"The brand's markets and its home market.","operationId":"getBrandMarkets","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketsRead"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/audiences":{"get":{"tags":["v1"],"summary":"Get Brand Audiences","description":"The brand's audiences, with All buyers first.","operationId":"getBrandAudiences","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudiencesRead"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/organizations/{organization_id}/usage":{"get":{"tags":["v1"],"summary":"Get Organization Usage","description":"Prompt use against the pool and content-credit use, for organization members.","operationId":"getOrganizationUsage","security":[{"apiKey":[]}],"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"An organization id; omit for the connected organization.","title":"Organization Id"},"description":"An organization id; omit for the connected organization."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Usage"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/organizations/{organization_id}/brands":{"get":{"tags":["v1"],"summary":"Get Organization Brands","description":"Portfolio rows with 1w figures, paired change and actions waiting.\n\nSet managed=true for accounts this manager actively manages. Brand grants\nalone open neither portfolio. Portfolio reads are live, with no scan pin.","operationId":"listOrganizationBrands","security":[{"apiKey":[]}],"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"An organization id; omit for the connected organization.","title":"Organization Id"},"description":"An organization id; omit for the connected organization."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"managed","in":"query","required":false,"schema":{"type":"boolean","description":"Include managed organizations.","default":false,"title":"Managed"},"description":"Include managed organizations."},{"name":"managed_account_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filter to this managed account, or use the manager's organization id for its own brands. Applies when managed=true; omitted returns managed accounts only.","title":"Managed Account Id"},"description":"Filter to this managed account, or use the manager's organization id for its own brands. Applies when managed=true; omitted returns managed accounts only."},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"enum":["score","actions","name"],"type":"string"},{"type":"null"}],"description":"Field to order results by.","title":"Sort"},"description":"Field to order results by."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/V1Portfolio"},{"$ref":"#/components/schemas/V1ManagerPortfolio"}],"title":"Response Listorganizationbrands"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/brands/{brand_id}/scans":{"get":{"tags":["v1"],"summary":"Get Scans","description":"The brand's weekly scans, daily scans and the Snapshot it carried in, newest first,\neach with the Heralded Score it issued.","operationId":"listScans","security":[{"apiKey":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The brand's UUID from listBrands.","title":"Brand Id"},"description":"The brand's UUID from listBrands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Scans"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/account/free-snapshot":{"get":{"tags":["v1"],"summary":"Get Free Snapshot","description":"Whether the credential owner's next Snapshot is free, and when it renews.\n\nUses the verified email's case and plus-tag normalization. A failed free run\nmakes the address available again. The daily platform cap is checked at start.","operationId":"getFreeSnapshot","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreeSnapshotStatus"}}}},"404":{"description":"No resource this caller can read.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/RateLimitProblem"},"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}}}}}},"security":[{"apiKey":[]}]}},"/v1/account/free-audit":{"get":{"tags":["v1"],"summary":"Get Free Audit","description":"Whether the credential owner's next Base audit is free, and when it renews.","operationId":"getFreeAudit","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreeSnapshotStatus"}}}},"404":{"description":"No resource this caller can read.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/RateLimitProblem"},"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}}}}}},"security":[{"apiKey":[]}]}},"/v1/scans":{"get":{"tags":["v1"],"summary":"Get Account Scans","description":"The Snapshots the key's owner ran, newest first, each with the Heralded Score it\nissued: the one-time scans no brand's list covers, including one that became a brand's\nfirst scan. A scan whose report is no longer served is left out.","operationId":"listAccountScans","security":[{"apiKey":[]}],"parameters":[{"name":"organization_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The workspace whose one-time scans to list. Omit for your own scans.","title":"Organization Id"},"description":"The workspace whose one-time scans to list. Omit for your own scans."},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}],"description":"Only your scans of this domain.","title":"Domain"},"description":"Only your scans of this domain."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Scans"}}}},"404":{"description":"No resource this caller can read.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}},"post":{"tags":["v1"],"summary":"Start Snapshot","description":"Start a Snapshot of a domain as the key's member, in its organization, and draft\nits profile: brand, description and market. Waits up to 15 seconds for the profile;\na null `profile` is still drafting, and getScan reads it later. Nothing is spent\nuntil runSnapshot. A domain whose Snapshot of yours has not run answers that\nSnapshot with 200. Needs a full-access key.","operationId":"startSnapshot","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotStart"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1StartedSnapshot"}}}},"404":{"description":"No resource this caller can read.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The key made more than 120 requests in the minute (`rate_limited`), or today's free Snapshots are all taken (`free_snapshots_exhausted`, with `resets_at`).","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"200":{"description":"Your Snapshot of this domain that has not run yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1StartedSnapshot"}}}},"403":{"description":"A read-only key or the web's session (`insufficient_scope`, with the scope challenge), or a member whose role cannot run Snapshots in the key's organization (`forbidden`).","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"description":"The scope challenge on `insufficient_scope`.","schema":{"type":"string"}}}},"422":{"description":"The domain is no website Heralded can read (`invalid_domain`), a platform's address (`platform_domain`), or the body is invalid (`invalid_request`).","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_domain","title":"Unprocessable Content","status":422,"detail":"The domain is not a website Heralded can read. Check its spelling.","code":"invalid_domain","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Nothing can pay: no free Snapshot and no Snapshot credit (`no_credits`), or every credit is held by your unrun Snapshots (`credits_held`). `resets_at` says when a free Snapshot opens again, where one will.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#no_credits","title":"Payment Required","status":402,"detail":"No free Snapshot or Snapshot credit can pay for this Snapshot.","code":"no_credits","instance":"example-request-id","resets_at":"2026-12-08T09:30:00+00:00"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"New scan starts are paused.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#scans_temporarily_paused","title":"Service Unavailable","status":503,"detail":"Heralded has paused new scan starts. Retry later.","code":"scans_temporarily_paused","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/audits":{"get":{"tags":["v1"],"summary":"Get Account Audits","description":"The Audits the key's owner ran, newest first. A delivered Audit's `share_id` reads\nit at `/v1/scans/{share_id}/audit`.","operationId":"listAccountAudits","security":[{"apiKey":[]}],"parameters":[{"name":"organization_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The workspace whose one-time scans to list. Omit for your own scans.","title":"Organization Id"},"description":"The workspace whose one-time scans to list. Omit for your own scans."},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}],"description":"Only your scans of this domain.","title":"Domain"},"description":"Only your scans of this domain."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Audits"}}}},"404":{"description":"No resource this caller can read.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/scans/{scan_id}":{"get":{"tags":["v1"],"summary":"Get Scan","description":"One scan: its progress while it runs, and once complete the score, Mentioned,\nRecommended and readiness it issued. A brand's scan is read by its readers, a\nSnapshot no brand holds or an Audit by the account that ran it. An Audit carries\naudit_progress instead of engine progress and issued AI figures.","operationId":"getScan","security":[{"apiKey":[]}],"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A scan UUID from getScan.","title":"Scan Id"},"description":"A scan UUID from getScan."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Scan"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/scans/{scan_id}/profile":{"post":{"tags":["v1"],"summary":"Edit Snapshot Profile","description":"Correct a Snapshot's profile before it runs. A changed brand, description or\nmarket drafts its questions again, and stops a Run waiting for the profile:\n`run_request.state` reads `stopped` and the Snapshot needs runSnapshot again.\nNeeds a full-access key.","operationId":"editSnapshotProfile","security":[{"apiKey":[]}],"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A Snapshot id from startSnapshot.","title":"Scan Id"},"description":"A Snapshot id from startSnapshot."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotProfileEdit"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Snapshot"}}}},"404":{"description":"No Snapshot of yours in the key's organization.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The Snapshot cannot take this step now: its profile is still drafting (`scan_not_ready`), it expired (`brief_expired`) or it already started; or the key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#scan_not_ready","title":"Conflict","status":409,"detail":"The Snapshot's profile is still drafting. Try again shortly.","code":"scan_not_ready","instance":"example-request-id","current_phase":"inferring_identity"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"403":{"description":"A read-only key or the web's session (`insufficient_scope`, with the scope challenge), or a member whose role cannot run Snapshots in the key's organization (`forbidden`).","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"description":"The scope challenge on `insufficient_scope`.","schema":{"type":"string"}}}},"422":{"description":"The scan id or a body field is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["body","market"],"msg":"Value error, expected one of global, europe, US","type":"value_error"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/scans/{scan_id}/run":{"post":{"tags":["v1"],"summary":"Run Snapshot","description":"Run a Snapshot on its member's free Snapshot, else one of the key's organization's\nSnapshot credits; `payer` says which. On a drafted profile it starts at once; while\nthe profile drafts, the run is recorded and starts when it is ready, and a refusal\nthen shows in `run_request`. Needs a full-access key.","operationId":"runSnapshot","security":[{"apiKey":[]}],"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A Snapshot id from startSnapshot.","title":"Scan Id"},"description":"A Snapshot id from startSnapshot."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Snapshot"}}}},"404":{"description":"No Snapshot of yours in the key's organization.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The Snapshot cannot take this step now: its profile is still drafting (`scan_not_ready`), it expired (`brief_expired`) or it already started; or the key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#scan_not_ready","title":"Conflict","status":409,"detail":"The Snapshot's profile is still drafting. Try again shortly.","code":"scan_not_ready","instance":"example-request-id","current_phase":"inferring_identity"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The key made more than 120 requests in the minute (`rate_limited`), or today's free Snapshots are all taken (`free_snapshots_exhausted`, with `resets_at`).","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"403":{"description":"A read-only key or the web's session (`insufficient_scope`, with the scope challenge), or a member whose role cannot run Snapshots in the key's organization (`forbidden`).","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"description":"The scope challenge on `insufficient_scope`.","schema":{"type":"string"}}}},"422":{"description":"The scan id or a body field is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["body","market"],"msg":"Value error, expected one of global, europe, US","type":"value_error"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"402":{"description":"Nothing can pay: no free Snapshot and no Snapshot credit (`no_credits`), or every credit is held by your unrun Snapshots (`credits_held`). `resets_at` says when a free Snapshot opens again, where one will.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#no_credits","title":"Payment Required","status":402,"detail":"No free Snapshot or Snapshot credit can pay for this Snapshot.","code":"no_credits","instance":"example-request-id","resets_at":"2026-12-08T09:30:00+00:00"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"New scan starts are paused.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#scans_temporarily_paused","title":"Service Unavailable","status":503,"detail":"Heralded has paused new scan starts. Retry later.","code":"scans_temporarily_paused","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/scans/{scan_id}/stop":{"post":{"tags":["v1"],"summary":"Stop Snapshot","description":"Cancel a run waiting for its Snapshot's profile, before anything is spent. A run\nthat has started goes on. Needs a full-access key.","operationId":"stopSnapshot","security":[{"apiKey":[]}],"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A Snapshot id from startSnapshot.","title":"Scan Id"},"description":"A Snapshot id from startSnapshot."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Snapshot"}}}},"404":{"description":"No Snapshot of yours in the key's organization.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The Snapshot cannot take this step now: its profile is still drafting (`scan_not_ready`), it expired (`brief_expired`) or it already started; or the key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#scan_not_ready","title":"Conflict","status":409,"detail":"The Snapshot's profile is still drafting. Try again shortly.","code":"scan_not_ready","instance":"example-request-id","current_phase":"inferring_identity"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"403":{"description":"A read-only key or the web's session (`insufficient_scope`, with the scope challenge), or a member whose role cannot run Snapshots in the key's organization (`forbidden`).","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"description":"The scope challenge on `insufficient_scope`.","schema":{"type":"string"}}}},"422":{"description":"The scan id or a body field is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["body","market"],"msg":"Value error, expected one of global, europe, US","type":"value_error"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/scans/{scan_id}/audit":{"get":{"tags":["v1"],"summary":"Get Scan Audit","description":"The Content read of a delivered Snapshot or Audit: every audited page ranked best fix\nfirst with what it fails, the page checks, the site's readability and the topics the site\nhas no page for, with an Audit's Website read, the brief and the brand's look. Only the\naccount that ran the scan reads it, a brand's other readers included; the shared read of\na Snapshot never carries it. `scan_id` is the scan's id, or the share id of its report\nlink.","operationId":"getScanAudit","security":[{"apiKey":[]}],"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A scan UUID from getScan.","title":"Scan Id"},"description":"A scan UUID from getScan."},{"name":"finding","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"A finding id whose pages start at finding_pages_offset.","title":"Finding"},"description":"A finding id whose pages start at finding_pages_offset."},{"name":"finding_pages_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"The pages listed under each finding.","default":10,"title":"Finding Pages Limit"},"description":"The pages listed under each finding."},{"name":"finding_pages_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages to skip within the selected finding.","default":0,"title":"Finding Pages Offset"},"description":"Pages to skip within the selected finding."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ScanAudit"}}}},"404":{"description":"No such scan, one the key's owner did not run, or no API key.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The API key is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/scans/{scan_id}/audit/map":{"get":{"tags":["v1"],"summary":"Get Scan Audit Map","description":"An Audit's own site map, for the account that ran it alone: every page in one\nlanguage with the links between them and what each holds back, or one folder of it.\nA Snapshot reads no website, so its map is unavailable.","operationId":"getScanAuditMap","security":[{"apiKey":[]}],"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A scan UUID from getScan.","title":"Scan Id"},"description":"A scan UUID from getScan."},{"name":"page","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"A page URL whose language to open when language is unset.","title":"Page"},"description":"A page URL whose language to open when language is unset."},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":35},{"type":"null"}],"description":"A code from languages; default the site's primary language.","title":"Language"},"description":"A code from languages; default the site's primary language."},{"name":"folder","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"A path such as /blog: its own pages and the folders under it, in place of every page. / is the top of the site.","title":"Folder"},"description":"A path such as /blog: its own pages and the folders under it, in place of every page. / is the top of the site."},{"name":"folder_pages_limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"The folder's pages listed, with folder.","default":50,"title":"Folder Pages Limit"},"description":"The folder's pages listed, with folder."},{"name":"folder_pages_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages to skip within the folder.","default":0,"title":"Folder Pages Offset"},"description":"Pages to skip within the folder."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SiteMap"}}}},"404":{"description":"No such scan, one the key's owner did not run, or no API key.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The API key is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/scans/{scan_id}/audit/pages":{"get":{"tags":["v1"],"summary":"Get Scan Audit Pages","description":"An Audit's own pages under filters, for the account that ran it alone, as a brand's\n`GET .../audit/pages` returns them. A Snapshot reads no website, so its pages are\nunavailable.","operationId":"listScanAuditPages","security":[{"apiKey":[]}],"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A scan UUID from getScan.","title":"Scan Id"},"description":"A scan UUID from getScan."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"A name from facets.","title":"Category"},"description":"A name from facets."},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":35},{"type":"null"}],"description":"A code from facets.","title":"Language"},"description":"A code from facets."},{"name":"findings","in":"query","required":false,"schema":{"anyOf":[{"enum":["issue","improve","none"],"type":"string"},{"type":"null"}],"description":"issue: holds an issue; improve: holds improvements and no issue; none: holds neither.","title":"Findings"},"description":"issue: holds an issue; improve: holds improvements and no issue; none: holds neither."},{"name":"access","in":"query","required":false,"schema":{"anyOf":[{"enum":["readable","blocked","unmeasured"],"type":"string"},{"type":"null"}],"description":"Whether AI engines can read the page: readable, blocked by any cause status names, or unmeasured (not_read).","title":"Access"},"description":"Whether AI engines can read the page: readable, blocked by any cause status names, or unmeasured (not_read)."},{"name":"changed","in":"query","required":false,"schema":{"anyOf":[{"enum":["new","changed"],"type":"string"},{"type":"null"}],"description":"Found, or its content changed, since the previous weekly read.","title":"Changed"},"description":"Found, or its content changed, since the previous weekly read."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["readable","blocked_robots","noindex","does_not_load","needs_javascript","not_read"],"type":"string"},{"type":"null"}],"description":"Filter by page status.","title":"Status"},"description":"Filter by page status."},{"name":"cited","in":"query","required":false,"schema":{"anyOf":[{"enum":["cited","not_cited"],"type":"string"},{"type":"null"}],"description":"Filter pages by citation state.","title":"Cited"},"description":"Filter pages by citation state."},{"name":"page_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["product","product_detail","collection","solution","pricing","blog_post","customer_story","press","documentation","resource","comparison","legal","home","about","contact","careers","landing","blog_index","utility","other"],"type":"string"},{"type":"null"}],"description":"Filter by page type.","title":"Page Type"},"description":"Filter by page type."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Text to search for.","title":"Q"},"description":"Text to search for."},{"name":"sort","in":"query","required":false,"schema":{"enum":["citations","page","status","crawls","read","findings","clicks"],"type":"string","description":"Field to order results by.","default":"citations","title":"Sort"},"description":"Field to order results by."},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"description":"Order results ascending or descending.","title":"Direction"},"description":"Order results ascending or descending."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SitePages"}}}},"404":{"description":"No such scan, one the key's owner did not run, or no API key.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The API key is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/scans/{scan_id}/audit/key-pages":{"get":{"tags":["v1"],"summary":"Get Scan Audit Key Pages","description":"An Audit's own key pages, for the account that ran it alone, as a brand's are read.\nTheir history is the one read the Audit made. A Snapshot's are unavailable.","operationId":"listScanAuditKeyPages","security":[{"apiKey":[]}],"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A scan UUID from getScan.","title":"Scan Id"},"description":"A scan UUID from getScan."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1KeyPages"}}}},"404":{"description":"No such scan, one the key's owner did not run, or no API key.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The API key is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/scans/{scan_id}/audit/key-pages/{path}":{"get":{"tags":["v1"],"summary":"Get Scan Audit Key Page","description":"One of an Audit's key pages, by its path without the leading slash.","operationId":"getScanAuditKeyPage","security":[{"apiKey":[]}],"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A scan UUID from getScan.","title":"Scan Id"},"description":"A scan UUID from getScan."},{"name":"path","in":"path","required":true,"schema":{"type":"string","description":"A key page path, such as /pricing.","title":"Path"},"description":"A key page path, such as /pricing."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1KeyPageDetail"}}}},"404":{"description":"No such scan, one the key's owner did not run, or no API key.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The API key is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/scans/{scan_id}/audit/competitors":{"get":{"tags":["v1"],"summary":"Get Scan Audit Competitors","description":"An Audit's rival comparison, for its owner. Base reads homepage screens;\nFull adds proof and copy similarity. A Snapshot's comparison is unavailable.","operationId":"listScanAuditCompetitors","security":[{"apiKey":[]}],"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A scan UUID from getScan.","title":"Scan Id"},"description":"A scan UUID from getScan."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"competitor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":300},{"type":"null"}],"description":"Filter by competitor key.","title":"Competitor"},"description":"Filter by competitor key."},{"name":"change","in":"query","required":false,"schema":{"anyOf":[{"enum":["new_page","removed_page","homepage_changed","pricing_changed","key_page_changed"],"type":"string"},{"type":"null"}],"description":"Filter by website change type.","title":"Change"},"description":"Filter by website change type."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1CompetitorSites"}}}},"404":{"description":"No such brand or answer, or the key's owner cannot read it.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"400":{"description":"The cursor is invalid or belongs to a different query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"A path or query parameter is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be less than or equal to 100","type":"less_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/shared/scans/{share_id}":{"get":{"tags":["v1"],"summary":"Get Shared Scan","description":"A delivered Snapshot through its share link. Public links need no sign-in;\nrestricted links require a workspace report reader, or the owner without a workspace.\nRevoked links return 404. Workspace analytics, search queries, crawl inventory,\ncontent strategy and per-viewer fields are never included.","operationId":"getSharedScan","parameters":[{"name":"share_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The share id from a shared report link.","title":"Share Id"},"description":"The share id from a shared report link."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SharedScan"}}}},"404":{"description":"No delivered scan has this share id.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"The scan was measured on a score formula Heralded no longer serves (scan_version_unsupported), or the report expired or was retired during pre-launch cleanup (report_retired).","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#scan_version_unsupported","title":"Gone","status":410,"detail":"This Snapshot was generated by an older version of Heralded. Run another Snapshot of the brand to see the current report.","code":"scan_version_unsupported","instance":"example-request-id","domain":"acme.com","rescan_url":"/snapshots?domain=acme.com"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The share id is not a UUID.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["path","share_id"],"msg":"Input should be a valid UUID","type":"uuid_parsing"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/shared/scans/{share_id}/questions/{query_id}/answers":{"get":{"tags":["v1"],"summary":"Get Shared Question Answers","description":"One shared question's masked full answers, 10 per page, and question-wide\nbrand and cited-page counts. Only brands shown in the report are named.","operationId":"listSharedQuestionAnswers","parameters":[{"name":"share_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The share id from a shared report link.","title":"Share Id"},"description":"The share id from a shared report link."},{"name":"query_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A question id from the shared report.","title":"Query Id"},"description":"A question id from the shared report."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":10,"description":"Fixed at 10 answers per page.","default":10,"title":"Limit"},"description":"Fixed at 10 answers per page."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"The preceding page's next_cursor.","title":"Cursor"},"description":"The preceding page's next_cursor."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SharedAnswers"}}}},"404":{"description":"No delivered scan has this share id.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"The scan was measured on a score formula Heralded no longer serves (scan_version_unsupported), or the report expired or was retired during pre-launch cleanup (report_retired).","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#scan_version_unsupported","title":"Gone","status":410,"detail":"This Snapshot was generated by an older version of Heralded. Run another Snapshot of the brand to see the current report.","code":"scan_version_unsupported","instance":"example-request-id","domain":"acme.com","rescan_url":"/snapshots?domain=acme.com"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The share id is not a UUID.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["path","share_id"],"msg":"Input should be a valid UUID","type":"uuid_parsing"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"400":{"description":"The cursor is invalid for this question.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/shared/scans/{share_id}/products":{"get":{"tags":["v1"],"summary":"Get Shared Products","description":"Every product of an ecommerce shared report's question, or of the brand or a\ncompetitor it shows, most shown first, with server paging. The report's own\n`shopping` lists are previews; these lists are complete. A brand the report\ndoes not show has its products counted in `hidden_products`, never named.","operationId":"listSharedProducts","parameters":[{"name":"share_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The share id from a shared report link.","title":"Share Id"},"description":"The share id from a shared report link."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"query_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Only the products shown in answers to this question.","title":"Query Id"},"description":"Only the products shown in answers to this question."},{"name":"maker","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"description":"Only this brand's products: your own key, or a competitor's, as `brand_keys` of the report's products section serves it.","title":"Maker"},"description":"Only this brand's products: your own key, or a competitor's, as `brand_keys` of the report's products section serves it."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SharedProducts"}}}},"404":{"description":"No delivered scan has this share id.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"The scan was measured on a score formula Heralded no longer serves (scan_version_unsupported), or the report expired or was retired during pre-launch cleanup (report_retired).","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#scan_version_unsupported","title":"Gone","status":410,"detail":"This Snapshot was generated by an older version of Heralded. Run another Snapshot of the brand to see the current report.","code":"scan_version_unsupported","instance":"example-request-id","domain":"acme.com","rescan_url":"/snapshots?domain=acme.com"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The share id is not a UUID.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["path","share_id"],"msg":"Input should be a valid UUID","type":"uuid_parsing"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"400":{"description":"The cursor is invalid for this query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/shared/scans/{share_id}/products/{product_id}":{"get":{"tags":["v1"],"summary":"Get Shared Product","description":"One product's details from a shared ecommerce report, even when it is\noutside the report's previews. A product of a brand the report does not show\nanswers 404, as does a product the report never showed.","operationId":"getSharedProduct","parameters":[{"name":"share_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The share id from a shared report link.","title":"Share Id"},"description":"The share id from a shared report link."},{"name":"product_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A product id from the shared report.","title":"Product Id"},"description":"A product id from the shared report."},{"name":"questions_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Questions per page (100).","default":20,"title":"Questions Limit"},"description":"Questions per page (100)."},{"name":"questions_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Questions to skip.","default":0,"title":"Questions Offset"},"description":"Questions to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SharedProduct"}}}},"404":{"description":"No delivered scan has this share id.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"The scan was measured on a score formula Heralded no longer serves (scan_version_unsupported), or the report expired or was retired during pre-launch cleanup (report_retired).","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#scan_version_unsupported","title":"Gone","status":410,"detail":"This Snapshot was generated by an older version of Heralded. Run another Snapshot of the brand to see the current report.","code":"scan_version_unsupported","instance":"example-request-id","domain":"acme.com","rescan_url":"/snapshots?domain=acme.com"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The share id is not a UUID.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["path","share_id"],"msg":"Input should be a valid UUID","type":"uuid_parsing"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/shared/scans/{share_id}/engines/{engine_id}/sites":{"get":{"tags":["v1"],"summary":"Get Shared Engine Sites","description":"Sites across one engine's rendered answers, with hidden competitors' URLs omitted.","operationId":"getSharedEngineSites","parameters":[{"name":"share_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The share id from a shared report link.","title":"Share Id"},"description":"The share id from a shared report link."},{"name":"engine_id","in":"path","required":true,"schema":{"type":"string","description":"An engine id from the shared report.","title":"Engine Id"},"description":"An engine id from the shared report."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SharedEngineSites"}}}},"404":{"description":"No delivered scan has this share id.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"The scan was measured on a score formula Heralded no longer serves (scan_version_unsupported), or the report expired or was retired during pre-launch cleanup (report_retired).","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#scan_version_unsupported","title":"Gone","status":410,"detail":"This Snapshot was generated by an older version of Heralded. Run another Snapshot of the brand to see the current report.","code":"scan_version_unsupported","instance":"example-request-id","domain":"acme.com","rescan_url":"/snapshots?domain=acme.com"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The share id is not a UUID.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["path","share_id"],"msg":"Input should be a valid UUID","type":"uuid_parsing"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/shared/audits/{share_id}":{"get":{"tags":["v1"],"summary":"Get Shared Audit","description":"A delivered Quick's frozen Website, key pages and map, with its share link alone.\nBase and Full results are owner-only and answer 404 here.","operationId":"getSharedAudit","parameters":[{"name":"share_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The share id from a shared report link.","title":"Share Id"},"description":"The share id from a shared report link."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SharedAudit"}}}},"404":{"description":"No delivered scan has this share id.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"The Quick's results were deleted 30 days after delivery.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#report_retired","title":"Gone","status":410,"detail":"This report was retired with Heralded's pre-launch data. Start a new Snapshot of the domain at rescan_url.","code":"report_retired","instance":"example-request-id","domain":"acme.com","rescan_url":"/snapshots?domain=acme.com"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The share id is not a UUID.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["path","share_id"],"msg":"Input should be a valid UUID","type":"uuid_parsing"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/leaderboards":{"get":{"tags":["v1"],"summary":"Get Leaderboards","description":"Published measurements under one market and optional filters. No credential required.","operationId":"getLeaderboards","parameters":[{"name":"industry","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"An industry slug from the facets.","title":"Industry"},"description":"An industry slug from the facets."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(?:[A-Z]{2}|europe)$"},{"type":"null"}],"description":"The market asked from: an ISO 3166-1 alpha-2 country, or `europe` for the board pooling the seven European countries. Omit it for Global.","title":"Country"},"description":"The market asked from: an ISO 3166-1 alpha-2 country, or `europe` for the board pooling the seven European countries. Omit it for Global."},{"name":"month","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Publication month as YYYY-MM; omit for the latest.","title":"Month"},"description":"Publication month as YYYY-MM; omit for the latest."},{"name":"side","in":"query","required":false,"schema":{"enum":["all","ai","search"],"type":"string","description":"AI and All use Heralded Scores and comparable history. Search keeps Google shares without a score or rank, and is empty where Google was not measured.","default":"all","title":"Side"},"description":"AI and All use Heralded Scores and comparable history. Search keeps Google shares without a score or rank, and is empty where Google was not measured."},{"name":"origin_country","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$"},{"type":"null"}],"description":"Brand origin as an ISO country code.","title":"Origin Country"},"description":"Brand origin as an ISO country code."},{"name":"order","in":"query","required":false,"schema":{"enum":["default","medals"],"type":"string","description":"Order by scores or podium places.","default":"default","title":"Order"},"description":"Order by scores or podium places."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Brand-name substring search.","title":"Q"},"description":"Brand-name substring search."},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"enum":["b2b","b2c","both"],"type":"string"},{"type":"null"}],"description":"Filter brands by their audience.","title":"Audience"},"description":"Filter brands by their audience."},{"name":"source_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["industry_authority","review","regulatory","media","educational","community","consulting","social","vendor","directory","unclassified"],"type":"string"},{"const":"brand_site","type":"string"},{"type":"null"}],"description":"Filter by source category.","title":"Source Type"},"description":"Filter by source category."},{"name":"include_brand_sites","in":"query","required":false,"schema":{"type":"boolean","description":"Include brand sites in the source ranking and its total.","default":false,"title":"Include Brand Sites"},"description":"Include brand sites in the source ranking and its total."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows to return, up to 100.","default":10,"title":"Limit"},"description":"Maximum rows to return, up to 100."},{"name":"brands_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in brands.","default":0,"title":"Brands Offset"},"description":"Rows to skip in brands."},{"name":"sources_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Sources to skip.","default":0,"title":"Sources Offset"},"description":"Sources to skip."},{"name":"source_pages_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in source pages.","default":0,"title":"Source Pages Offset"},"description":"Rows to skip in source pages."},{"name":"engines_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in engines.","default":0,"title":"Engines Offset"},"description":"Rows to skip in engines."},{"name":"prompts_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Related prompts to skip.","default":0,"title":"Prompts Offset"},"description":"Related prompts to skip."},{"name":"movers_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in movers.","default":0,"title":"Movers Offset"},"description":"Rows to skip in movers."},{"name":"dropouts_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in dropouts.","default":0,"title":"Dropouts Offset"},"description":"Rows to skip in dropouts."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Leaderboard"}}}},"404":{"description":"No published leaderboard contains this brand or source.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid filters or pagination.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be greater than or equal to 1","type":"greater_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"429":{"description":"The anonymous IP or site-key bucket is exhausted.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":60,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"schema":{"type":"integer","example":60}}}}}}},"/v1/leaderboards/hall-of-fame":{"get":{"tags":["v1"],"summary":"Get Hall Of Fame","description":"Every ranked brand in scope, ordered by first, second and third places, then best rank,\nbest Heralded Score and name. Brands equal on every key share a place. Each row includes\nits best three placements. Origin filters brands; an excluded country narrows Europe.","operationId":"getLeaderboardHallOfFame","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows to return, up to 100.","default":10,"title":"Limit"},"description":"Maximum rows to return, up to 100."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip.","default":0,"title":"Offset"},"description":"Rows to skip."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"The preceding page's next_cursor.","title":"Cursor"},"description":"The preceding page's next_cursor."},{"name":"industry","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"An industry slug from the facets.","title":"Industry"},"description":"An industry slug from the facets."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(?:[A-Z]{2}|global|europe)$"},{"type":"null"}],"description":"Global, an ISO country, or `europe` for the sum of the seven countries' boards. The pooled Europe board never counts. Omit to count Global and all countries.","title":"Market"},"description":"Global, an ISO country, or `europe` for the sum of the seven countries' boards. The pooled Europe board never counts. Omit to count Global and all countries."},{"name":"exclude_country","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$"},{"type":"null"}],"description":"ISO country to leave out of a `market=europe` scope, or, with `market` omitted, of Global and all countries.","title":"Exclude Country"},"description":"ISO country to leave out of a `market=europe` scope, or, with `market` omitted, of Global and all countries."},{"name":"origin_country","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$"},{"type":"null"}],"description":"Keep brands whose origin (`hq_country`) is this ISO country.","title":"Origin Country"},"description":"Keep brands whose origin (`hq_country`) is this ISO country."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HallOfFame"}}}},"404":{"description":"No published leaderboard contains this brand or source.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid filters or pagination.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be greater than or equal to 1","type":"greater_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"429":{"description":"The anonymous IP or site-key bucket is exhausted.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":60,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"schema":{"type":"integer","example":60}}}}}}},"/v1/leaderboards/facets":{"get":{"tags":["v1"],"summary":"Get Facets","description":"Leaderboard page catalogue and available filters. No credential required.","operationId":"getLeaderboardFacets","parameters":[{"name":"month","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Publication month as YYYY-MM; omit for the latest.","title":"Month"},"description":"Publication month as YYYY-MM; omit for the latest."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacetsRead"}}}},"404":{"description":"No published leaderboard contains this brand or source.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid filters or pagination.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be greater than or equal to 1","type":"greater_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"429":{"description":"The anonymous IP or site-key bucket is exhausted.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":60,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"schema":{"type":"integer","example":60}}}}}}},"/v1/leaderboards/hall-of-fame/sources":{"get":{"tags":["v1"],"summary":"Get Sources Hall Of Fame","description":"Sources' podium places across current boards. No credential required.","operationId":"getLeaderboardSourcesHallOfFame","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows to return, up to 100.","default":10,"title":"Limit"},"description":"Maximum rows to return, up to 100."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip.","default":0,"title":"Offset"},"description":"Rows to skip."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"The preceding page's next_cursor.","title":"Cursor"},"description":"The preceding page's next_cursor."},{"name":"industry","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"An industry slug from the facets.","title":"Industry"},"description":"An industry slug from the facets."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(?:[A-Z]{2}|global|europe)$"},{"type":"null"}],"description":"Global, an ISO country, or `europe` for the sum of the seven countries' boards. The pooled Europe board never counts. Omit to count Global and all countries.","title":"Market"},"description":"Global, an ISO country, or `europe` for the sum of the seven countries' boards. The pooled Europe board never counts. Omit to count Global and all countries."},{"name":"exclude_country","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$"},{"type":"null"}],"description":"ISO country to leave out of a `market=europe` scope, or, with `market` omitted, of Global and all countries.","title":"Exclude Country"},"description":"ISO country to leave out of a `market=europe` scope, or, with `market` omitted, of Global and all countries."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcesHallOfFame"}}}},"404":{"description":"No published leaderboard contains this brand or source.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid filters or pagination.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be greater than or equal to 1","type":"greater_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"429":{"description":"The anonymous IP or site-key bucket is exhausted.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":60,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"schema":{"type":"integer","example":60}}}}}}},"/v1/leaderboards/brands/{slug}":{"get":{"tags":["v1"],"summary":"Get Brand","description":"A brand's published placements, highlights, sources and history. No credential required.","operationId":"getLeaderboardBrand","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"A brand slug from a leaderboard.","title":"Slug"},"description":"A brand slug from a leaderboard."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows to return, up to 100.","default":10,"title":"Limit"},"description":"Maximum rows to return, up to 100."},{"name":"brands_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in brands.","default":0,"title":"Brands Offset"},"description":"Rows to skip in brands."},{"name":"placements_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in placements.","default":0,"title":"Placements Offset"},"description":"Rows to skip in placements."},{"name":"engines_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in engines.","default":0,"title":"Engines Offset"},"description":"Rows to skip in engines."},{"name":"engine_ranks_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in engine ranks.","default":0,"title":"Engine Ranks Offset"},"description":"Rows to skip in engine ranks."},{"name":"questions_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in questions.","default":0,"title":"Questions Offset"},"description":"Rows to skip in questions."},{"name":"highlights_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in highlights.","default":0,"title":"Highlights Offset"},"description":"Rows to skip in highlights."},{"name":"sources_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Sources to skip.","default":0,"title":"Sources Offset"},"description":"Sources to skip."},{"name":"source_pages_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in source pages.","default":0,"title":"Source Pages Offset"},"description":"Rows to skip in source pages."},{"name":"history_series_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in history series.","default":0,"title":"History Series Offset"},"description":"Rows to skip in history series."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandDetail"}}}},"404":{"description":"No published leaderboard contains this brand or source.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid filters or pagination.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be greater than or equal to 1","type":"greater_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"429":{"description":"The anonymous IP or site-key bucket is exhausted.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":60,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"schema":{"type":"integer","example":60}}}}}}},"/v1/leaderboards/sources/{domain}":{"get":{"tags":["v1"],"summary":"Get Source","description":"A source's published placements, pages, brands and engines. No credential required.","operationId":"getLeaderboardSource","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","maxLength":253,"pattern":"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$","description":"A source domain, such as g2.com.","title":"Domain"},"description":"A source domain, such as g2.com."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows to return, up to 100.","default":10,"title":"Limit"},"description":"Maximum rows to return, up to 100."},{"name":"brands_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in brands.","default":0,"title":"Brands Offset"},"description":"Rows to skip in brands."},{"name":"placements_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in placements.","default":0,"title":"Placements Offset"},"description":"Rows to skip in placements."},{"name":"engines_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in engines.","default":0,"title":"Engines Offset"},"description":"Rows to skip in engines."},{"name":"engine_ranks_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in engine ranks.","default":0,"title":"Engine Ranks Offset"},"description":"Rows to skip in engine ranks."},{"name":"questions_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in questions.","default":0,"title":"Questions Offset"},"description":"Rows to skip in questions."},{"name":"highlights_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in highlights.","default":0,"title":"Highlights Offset"},"description":"Rows to skip in highlights."},{"name":"sources_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Sources to skip.","default":0,"title":"Sources Offset"},"description":"Sources to skip."},{"name":"source_pages_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in source pages.","default":0,"title":"Source Pages Offset"},"description":"Rows to skip in source pages."},{"name":"history_series_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip in history series.","default":0,"title":"History Series Offset"},"description":"Rows to skip in history series."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceDetail"}}}},"404":{"description":"No published leaderboard contains this brand or source.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid filters or pagination.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["query","limit"],"msg":"Input should be greater than or equal to 1","type":"greater_than_equal"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"429":{"description":"The anonymous IP or site-key bucket is exhausted.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":60,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"schema":{"type":"integer","example":60}}}}}}},"/v1/service/snapshots":{"post":{"tags":["service"],"summary":"Start Snapshot","description":"Start a Snapshot using one organization credit. Replays return its original ids.","operationId":"startServiceSnapshot","security":[{"serviceToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}],"description":"A workspace-unique key. Reuse it only with the same request payload.","title":"Idempotency-Key"},"description":"A workspace-unique key. Reuse it only with the same request payload."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSnapshot"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartedSnapshot"}}}},"404":{"description":"No resource this token can read.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"402":{"description":"The organization has no scan credits.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#no_credits","title":"Payment Required","status":402,"detail":"No free Snapshot or Snapshot credit can pay for this Snapshot.","code":"no_credits","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The organization is archived or the key names another product.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Snapshot request is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["body","runs_per_prompt"],"msg":"Input should be 1 or 2","type":"literal_error"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"503":{"description":"New scan starts are paused.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#scans_temporarily_paused","title":"Service Unavailable","status":503,"detail":"Heralded has paused new scan starts. Retry later.","code":"scans_temporarily_paused","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"200":{"description":"Idempotent replay; Idempotent-Replayed is true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartedSnapshot"}}}}}}},"/v1/service/snapshots/{scan_id}":{"get":{"tags":["service"],"summary":"Get Snapshot","description":"Read a Snapshot started by this service token's organization.","operationId":"getServiceSnapshot","security":[{"serviceToken":[]}],"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The scan id returned by a service Snapshot start.","title":"Scan Id"},"description":"The scan id returned by a service Snapshot start."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Scan"}}}},"404":{"description":"No service Snapshot this token can read.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"402":{"description":"The organization has no scan credits.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#no_credits","title":"Payment Required","status":402,"detail":"No free Snapshot or Snapshot credit can pay for this Snapshot.","code":"no_credits","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The organization is archived or the key names another product.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Snapshot request is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["body","runs_per_prompt"],"msg":"Input should be 1 or 2","type":"literal_error"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"503":{"description":"New scan starts are paused.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#scans_temporarily_paused","title":"Service Unavailable","status":503,"detail":"Heralded has paused new scan starts. Retry later.","code":"scans_temporarily_paused","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/service/audits":{"post":{"tags":["service"],"summary":"Start Audit","description":"Start a Full audit with your brief and competitors. Reuse Idempotency-Key only for the\nsame request.","operationId":"startServiceAudit","security":[{"serviceToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}],"description":"A workspace-unique key. Reuse it only with the same request payload.","title":"Idempotency-Key"},"description":"A workspace-unique key. Reuse it only with the same request payload."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartAudit"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartedAudit"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"404":{"description":"No service audit or page this token can read.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The organization is archived or the key names another product.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#idempotency_key_reused","title":"Conflict","status":409,"detail":"Conflict","code":"idempotency_key_reused","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The request is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["body","queries"],"msg":"Exactly 20 queries are required.","type":"too_short"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"200":{"description":"Idempotent replay; Idempotent-Replayed is true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartedAudit"}}}},"402":{"description":"The organization has no scan credits.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#no_credits","title":"Payment Required","status":402,"detail":"No free Snapshot or Snapshot credit can pay for this Snapshot.","code":"no_credits","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"New scan starts are paused.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#scans_temporarily_paused","title":"Service Unavailable","status":503,"detail":"Heralded has paused new scan starts. Retry later.","code":"scans_temporarily_paused","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/service/audits/{scan_id}":{"get":{"tags":["service"],"summary":"Get Audit","description":"Read the service audit's progress, Website figures, brief, page collections, raw metrics\nand full-page screenshots.","operationId":"getServiceAudit","security":[{"serviceToken":[]}],"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A scan UUID from getScan.","title":"Scan Id"},"description":"A scan UUID from getScan."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceAudit"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"404":{"description":"No service audit or page this token can read.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The request is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["body","queries"],"msg":"Exactly 20 queries are required.","type":"too_short"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/service/audits/{scan_id}/pages":{"get":{"tags":["service"],"summary":"Get Pages","description":"List the audit's pages with findings, citations, filters and content hashes.","operationId":"listServiceAuditPages","security":[{"serviceToken":[]}],"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A scan UUID from getScan.","title":"Scan Id"},"description":"A scan UUID from getScan."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"A name from facets.","title":"Category"},"description":"A name from facets."},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":35},{"type":"null"}],"description":"A code from facets.","title":"Language"},"description":"A code from facets."},{"name":"findings","in":"query","required":false,"schema":{"anyOf":[{"enum":["issue","improve","none"],"type":"string"},{"type":"null"}],"description":"issue: holds an issue; improve: holds improvements and no issue; none: holds neither.","title":"Findings"},"description":"issue: holds an issue; improve: holds improvements and no issue; none: holds neither."},{"name":"access","in":"query","required":false,"schema":{"anyOf":[{"enum":["readable","blocked","unmeasured"],"type":"string"},{"type":"null"}],"description":"Whether AI engines can read the page: readable, blocked by any cause status names, or unmeasured (not_read).","title":"Access"},"description":"Whether AI engines can read the page: readable, blocked by any cause status names, or unmeasured (not_read)."},{"name":"changed","in":"query","required":false,"schema":{"anyOf":[{"enum":["new","changed"],"type":"string"},{"type":"null"}],"description":"Found, or its content changed, since the previous weekly read.","title":"Changed"},"description":"Found, or its content changed, since the previous weekly read."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["readable","blocked_robots","noindex","does_not_load","needs_javascript","not_read"],"type":"string"},{"type":"null"}],"description":"Filter by page status.","title":"Status"},"description":"Filter by page status."},{"name":"cited","in":"query","required":false,"schema":{"anyOf":[{"enum":["cited","not_cited"],"type":"string"},{"type":"null"}],"description":"Filter pages by citation state.","title":"Cited"},"description":"Filter pages by citation state."},{"name":"page_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["product","product_detail","collection","solution","pricing","blog_post","customer_story","press","documentation","resource","comparison","legal","home","about","contact","careers","landing","blog_index","utility","other"],"type":"string"},{"type":"null"}],"description":"Filter by page type.","title":"Page Type"},"description":"Filter by page type."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Text to search for.","title":"Q"},"description":"Text to search for."},{"name":"sort","in":"query","required":false,"schema":{"enum":["citations","page","status","crawls","read","findings","clicks"],"type":"string","description":"Field to order results by.","default":"citations","title":"Sort"},"description":"Field to order results by."},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"description":"Order results ascending or descending.","title":"Direction"},"description":"Order results ascending or descending."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServicePages"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"404":{"description":"No service audit or page this token can read.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The request is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["body","queries"],"msg":"Exactly 20 queries are required.","type":"too_short"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"400":{"description":"The cursor is invalid or names another query.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_cursor","title":"Bad Request","status":400,"detail":"The cursor is invalid or belongs to a different query.","code":"invalid_cursor","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/service/audits/{scan_id}/key-pages":{"get":{"tags":["service"],"summary":"Get Key Pages","description":"List the audit's key pages with their visual assessments and content hashes.","operationId":"listServiceAuditKeyPages","security":[{"serviceToken":[]}],"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A scan UUID from getScan.","title":"Scan Id"},"description":"A scan UUID from getScan."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum rows (100).","default":20,"title":"Limit"},"description":"Maximum rows (100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"Prior next_cursor; keep filters and limit.","title":"Cursor"},"description":"Prior next_cursor; keep filters and limit."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Completed scan id cutoff.","title":"As Of"},"description":"Completed scan id cutoff."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip; prefer cursor paging.","default":0,"title":"Offset"},"description":"Rows to skip; prefer cursor paging."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceKeyPages"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"404":{"description":"No service audit or page this token can read.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The request is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["body","queries"],"msg":"Exactly 20 queries are required.","type":"too_short"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/service/audits/{scan_id}/map":{"get":{"tags":["service"],"summary":"Get Map","description":"Read one folder of the audit's website map, including its pages and links.","operationId":"getServiceAuditMap","security":[{"serviceToken":[]}],"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A scan UUID from getScan.","title":"Scan Id"},"description":"A scan UUID from getScan."},{"name":"page","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"A page URL whose language to open when language is unset.","title":"Page"},"description":"A page URL whose language to open when language is unset."},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":35},{"type":"null"}],"description":"A code from languages; default the site's primary language.","title":"Language"},"description":"A code from languages; default the site's primary language."},{"name":"folder","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"A path such as /blog: its own pages and the folders under it, in place of every page. / is the top of the site.","title":"Folder"},"description":"A path such as /blog: its own pages and the folders under it, in place of every page. / is the top of the site."},{"name":"folder_pages_limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"The folder's pages listed, with folder.","default":50,"title":"Folder Pages Limit"},"description":"The folder's pages listed, with folder."},{"name":"folder_pages_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages to skip within the folder.","default":0,"title":"Folder Pages Offset"},"description":"Pages to skip within the folder."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SiteMap"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"404":{"description":"No service audit or page this token can read.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The request is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["body","queries"],"msg":"Exactly 20 queries are required.","type":"too_short"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/service/audits/{scan_id}/pages/text":{"get":{"tags":["service"],"summary":"Get Text","description":"Read retained text for a page URL in this audit; expired text answers 410.","operationId":"getServiceAuditPageText","security":[{"serviceToken":[]}],"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A scan UUID from getScan.","title":"Scan Id"},"description":"A scan UUID from getScan."},{"name":"url","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"The page URL to select.","title":"Url"},"description":"The page URL to select."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServicePageText"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"404":{"description":"No service audit or page this token can read.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The request is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["body","queries"],"msg":"Exactly 20 queries are required.","type":"too_short"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"410":{"description":"The page body is no longer retained.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#page_text_expired","title":"Gone","status":410,"detail":"Gone","code":"page_text_expired","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/service/audits/{scan_id}/screenshots/{device}":{"get":{"tags":["service"],"summary":"Get Screenshot","description":"Download one of the audit's full-page screenshots; `screenshots` links here.","operationId":"getServiceAuditScreenshot","security":[{"serviceToken":[]}],"parameters":[{"name":"device","in":"path","required":true,"schema":{"enum":["desktop","phone"],"type":"string","description":"Which screenshot: desktop or phone.","title":"Device"},"description":"Which screenshot: desktop or phone."},{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"A scan UUID from getScan.","title":"Scan Id"},"description":"A scan UUID from getScan."}],"responses":{"200":{"description":"The screenshot image.","content":{"image/*":{}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}},"429":{"description":"The API key made more than 120 requests in the minute.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#rate_limited","title":"Too Many Requests","status":429,"detail":"This caller is past its requests for the minute. Retry after the seconds in Retry-After.","code":"rate_limited","instance":"example-request-id","rate_limit":{"limit":120,"window":60,"remaining":0,"reset":60}},"schema":{"$ref":"#/components/schemas/RateLimitProblem"}}},"headers":{"Retry-After":{"description":"Seconds until the key may call again.","schema":{"type":"integer","example":60}}}},"404":{"description":"No service audit or page this token can read.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#not_found","title":"Not Found","status":404,"detail":"Nothing here that this API key can read.","code":"not_found","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The API key's organization is archived.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#workspace_archived","title":"Conflict","status":409,"detail":"The API key's organization is archived.","code":"workspace_archived","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The request is invalid.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["body","queries"],"msg":"Exactly 20 queries are required.","type":"too_short"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}}}}},"/v1/service/quick-audits":{"post":{"tags":["service"],"summary":"Start Quick Audit","description":"Start a Quick audit without spending a scan credit.","operationId":"startServiceQuickAudit","security":[{"serviceToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}],"description":"A workspace-unique key. Reuse it only with the same request payload.","title":"Idempotency-Key"},"description":"A workspace-unique key. Reuse it only with the same request payload."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartQuickAudit"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartedAudit"}}}},"400":{"description":"The Idempotency-Key header is required.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Bad Request","status":400,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No API key, or one that is unknown, revoked or expired.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_token","title":"Unauthorized","status":401,"detail":"The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.","code":"invalid_token","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string","example":"Bearer"}}}},"403":{"description":"The service token lacks the required scope.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#insufficient_scope","title":"Forbidden","status":403,"detail":"The credential does not have the scope this operation requires.","code":"insufficient_scope","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}},"409":{"description":"The organization is archived or the key names another product.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#idempotency_key_reused","title":"Conflict","status":409,"detail":"Conflict","code":"idempotency_key_reused","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The request is invalid (invalid_request), its domain has no DNS record (invalid_domain), or the key names a different payload (idempotency_key_reused).","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#invalid_request","title":"Unprocessable Content","status":422,"detail":"The request's parameters are invalid; `errors` names each one.","code":"invalid_request","instance":"example-request-id","errors":[{"loc":["body","domain"],"msg":"Field required","type":"missing"}]},"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"429":{"description":"The workspace's daily Quick audit cap is exhausted, or the token is rate limited.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#quick_audits_exhausted","title":"Too Many Requests","status":429,"detail":"Too Many Requests","code":"quick_audits_exhausted","instance":"example-request-id","resets_at":"2026-10-21T00:00:00+00:00"},"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Retry-After":{"description":"Seconds until the workspace may start another Quick audit.","schema":{"type":"integer","example":3600}}}},"503":{"description":"New scan starts are paused.","content":{"application/problem+json":{"example":{"type":"https://docs.heralded.ai/errors-and-limits#scans_temporarily_paused","title":"Service Unavailable","status":503,"detail":"Heralded has paused new scan starts. Retry later.","code":"scans_temporarily_paused","instance":"example-request-id"},"schema":{"$ref":"#/components/schemas/Problem"}}}},"200":{"description":"Idempotent replay; Idempotent-Replayed is true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartedAudit"}}}}}}}},"components":{"schemas":{"AIOverviewCounts":{"properties":{"cites_you":{"type":"integer","title":"Cites You","description":"Members whose AI Overview cites your pages.","default":0},"cites_others":{"type":"integer","title":"Cites Others","description":"Members with an AI Overview not citing you.","default":0},"none":{"type":"integer","title":"None","description":"Members checked without an AI Overview.","default":0},"unchecked":{"type":"integer","title":"Unchecked","description":"Members without a known AI Overview result.","default":0}},"type":"object","required":["cites_you","cites_others","none","unchecked"],"title":"AIOverviewCounts"},"ActionResults":{"properties":{"first_citation":{"anyOf":[{"$ref":"#/components/schemas/FirstCitation"},{"type":"null"}],"description":"First qualifying citation after this publication; null until one is observed."},"citations":{"items":{"$ref":"#/components/schemas/FirstCitation"},"type":"array","title":"Citations","description":"First observation per engine and stable prompt, capped at five within the measurement window."},"citation_count":{"type":"integer","title":"Citation Count","description":"Distinct engine and stable prompt pairs in the publication measurement window, before the five-row cap.","default":0},"engine_count":{"type":"integer","title":"Engine Count","description":"Distinct engines citing this publication within its measurement window, before the list cap.","default":0},"prompt_count":{"type":"integer","title":"Prompt Count","description":"Distinct stable prompts citing this publication within its measurement window, across engines and before the list cap.","default":0},"status_label":{"type":"string","enum":["Delivered","Cited","Paying off"],"title":"Status Label","description":"Paying off requires verification of the targeted answer metric against untouched questions; otherwise a tracked citation takes precedence over delivery.","default":"Delivered"},"steps":{"items":{"$ref":"#/components/schemas/ResultStep"},"type":"array","title":"Steps","description":"One step per declared tracking signal, in play order, then the measured answer outcome. Includes pending, unchanged, unavailable and inconclusive states. A site fix's verification is its live step."},"headline":{"anyOf":[{"$ref":"#/components/schemas/ResultEntry"},{"type":"null"}],"description":"Verified gain, otherwise the first citation; absent until either exists."},"results":{"items":{"$ref":"#/components/schemas/ResultEntry"},"type":"array","title":"Results","description":"Confirmed citation, publication, crawler, ranking and Search Console observations."},"targeted_prompts":{"items":{"$ref":"#/components/schemas/ResultEntry"},"type":"array","title":"Targeted Prompts","description":"New brand mentions on prompts this work targets; no claim that the page was cited."},"watching":{"items":{"$ref":"#/components/schemas/ResultEntry"},"type":"array","title":"Watching","description":"Pending and unchanged signals with something to watch."},"warnings":{"items":{"$ref":"#/components/schemas/ResultEntry"},"type":"array","title":"Warnings","description":"Signals whose reads failed, excluding missing connections."},"connect":{"anyOf":[{"$ref":"#/components/schemas/ConnectResults"},{"type":"null"}],"description":"Neutral connection offer for the missing sources, or null when none are missing."},"measured":{"anyOf":[{"$ref":"#/components/schemas/ResultEntry"},{"type":"null"}],"description":"Measured outcome or its due date, separate from citation observations."}},"type":"object","required":["first_citation","citations","citation_count","engine_count","prompt_count","status_label","steps","headline","results","targeted_prompts","watching","warnings","connect","measured"],"title":"ActionResults"},"ActionSection":{"properties":{"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Next page of this section, with the same section and limit."},"key":{"type":"string","title":"Key","description":"The section being paged."},"total":{"type":"integer","title":"Total","description":"All rows in this section before paging."},"offset":{"type":"integer","title":"Offset","description":"Rows skipped in this section."},"limit":{"type":"integer","title":"Limit","description":"Maximum rows in this section page."}},"type":"object","required":["next_cursor","key","total","offset","limit"],"title":"ActionSection"},"ActionViewerResponse":{"properties":{"sender_choices":{"anyOf":[{"$ref":"#/components/schemas/SenderChoices"},{"type":"null"}],"description":"Viewer-specific sender groups for an email task; null for other work or redacted text."},"sender_suggestion":{"anyOf":[{"$ref":"#/components/schemas/SenderSuggestion"},{"type":"null"}],"description":"The viewer's sole personal mailbox, otherwise the sole shared mailbox; null without a unique suggestion."},"approvable":{"type":"boolean","title":"Approvable","description":"Whether this viewer may approve from the task's stored sender.","default":true},"sender_owner_first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sender Owner First Name","description":"The stored mailbox owner's first name, when available."},"sender_owner_account_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Sender Owner Account Id","description":"The stored mailbox owner's account ID, to assign the task to them; null without an owner."},"sender_gap":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sender Gap","description":"The choice still owed when neither a sender nor a suggestion exists."},"picks_up_work":{"type":"boolean","title":"Picks Up Work","description":"Whether this work area starts suggestions automatically.","default":false},"kit":{"anyOf":[{"$ref":"#/components/schemas/SiteKitResponse"},{"type":"null"}],"description":"The current fix kit, null without a kit."},"redrafts_left":{"type":"integer","title":"Redrafts Left","description":"Free short-draft revisions remaining."},"assigned_to_you":{"type":"boolean","title":"Assigned To You","description":"Whether the work is assigned to this caller.","default":false},"thread":{"items":{"$ref":"#/components/schemas/ThreadStepViewer"},"type":"array","title":"Thread","description":"Viewer-specific names for the returned activity events."}},"type":"object","required":["sender_choices","sender_suggestion","approvable","sender_owner_first_name","sender_owner_account_id","sender_gap","picks_up_work","kit","redrafts_left","assigned_to_you","thread"],"title":"ActionViewerResponse"},"AgentAnswers":{"properties":{"used":{"type":"integer","title":"Used"},"cap":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cap"}},"type":"object","required":["used","cap"],"title":"AgentAnswers"},"AliasRow":{"properties":{"name":{"type":"string","title":"Name"},"source":{"type":"string","enum":["name","profile","product","domain"],"title":"Source"},"removable":{"type":"boolean","title":"Removable"}},"type":"object","required":["name","source","removable"],"title":"AliasRow","description":"One name that counts as a mention.\n\n`source` says where it came from: `name` is the brand's own name,\n`product` one of its product lines and `domain` the registrable label of\nits site, all derived and none removable here; `profile` is one somebody\nadded."},"AnswerHighlightSpan":{"properties":{"start":{"type":"integer","minimum":0.0,"title":"Start"},"end":{"type":"integer","minimum":0.0,"title":"End"},"brand":{"type":"string","enum":["you","rival"],"title":"Brand"}},"type":"object","required":["start","end","brand"],"title":"AnswerHighlightSpan","description":"One place the answer names the brand or a rival, for the overlay to\nmark: half-open offsets into `answer_text`, counted in Unicode code\npoints, with `you` for the brand's own names and `rival` for a rival's."},"AnswerReadSegment":{"properties":{"label":{"type":"string","title":"Label"},"persona_id":{"type":"string","title":"Persona Id"},"geo":{"type":"string","title":"Geo"}},"type":"object","required":["label","persona_id","geo"],"title":"AnswerReadSegment"},"AnswerReadStates":{"properties":{"mentioned":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Mentioned"},"understood":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Understood"},"recommended":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Recommended"},"praised":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Praised"},"icon_states":{"$ref":"#/components/schemas/IconStates","readOnly":true}},"type":"object","required":["mentioned","understood","recommended","praised","icon_states"],"title":"AnswerReadStates","description":"The four words for how one answer treated the brand (D32, D37).\n\nThe wire shape of `app.scans.scoring.axes.AnswerAxes`, which is where the\nreading itself is decided — the report, the roll-ups and this history all\nread one answer the same way. `None` is unmeasured and never a zero."},"AnswersLink":{"properties":{"href":{"type":"string","title":"Href"}},"type":"object","required":["href"],"title":"AnswersLink"},"AskedCountry":{"properties":{"country":{"type":"string","title":"Country"},"language":{"type":"string","title":"Language"}},"type":"object","required":["country","language"],"title":"AskedCountry","description":"A country a Europe Snapshot asked from, and its own language there."},"AssetOption":{"properties":{"value":{"type":"string","title":"Value","description":"The filter value."},"label":{"type":"string","title":"Label","description":"The filter label."}},"type":"object","required":["value","label"],"title":"AssetOption"},"AssigneeResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"initials":{"type":"string","title":"Initials"}},"type":"object","required":["id","name","initials"],"title":"AssigneeResponse"},"Attribution":{"properties":{"period":{"type":"string","title":"Period"},"total":{"type":"integer","title":"Total"},"by_voice":{"items":{"$ref":"#/components/schemas/AttributionVoice"},"type":"array","title":"By Voice"}},"type":"object","required":["period","total","by_voice"],"title":"Attribution"},"AttributionVoice":{"properties":{"voice":{"type":"string","title":"Voice"},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["voice","platform","count"],"title":"AttributionVoice"},"AudienceOption":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Id","description":"Audience UUID; null for All buyers."},"name":{"type":"string","title":"Name","description":"Audience name."},"description":{"type":"string","title":"Description","description":"Who the audience is; empty for All buyers."}},"type":"object","required":["id","name","description"],"title":"AudienceOption"},"AudiencesRead":{"properties":{"audiences":{"items":{"$ref":"#/components/schemas/AudienceOption"},"type":"array","title":"Audiences","description":"Available audiences, All buyers first."}},"type":"object","required":["audiences"],"title":"AudiencesRead"},"AuditCategoryFacet":{"properties":{"name":{"type":"string","title":"Name"},"group":{"type":"string","enum":["Site","Content","Support","Other"],"title":"Group"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["name","group","count"],"title":"AuditCategoryFacet"},"AuditCompetitor":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name"},"domain":{"type":"string","maxLength":253,"minLength":1,"title":"Domain"}},"additionalProperties":false,"type":"object","required":["name","domain"],"title":"AuditCompetitor"},"AuditFacets":{"properties":{"categories":{"items":{"$ref":"#/components/schemas/AuditCategoryFacet"},"type":"array","title":"Categories"},"languages":{"items":{"$ref":"#/components/schemas/AuditLanguageFacet"},"type":"array","title":"Languages"}},"type":"object","required":["categories","languages"],"title":"AuditFacets","description":"Each category counts the pages under every filter but the category's, so a\nchip's count is the total the table would show with that chip chosen and the\nother chips keep theirs. Each language counts the pages under every filter\nbut language, so the other language options stay available."},"AuditLanguageFacet":{"properties":{"code":{"type":"string","title":"Code"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["code","count"],"title":"AuditLanguageFacet"},"AuditPageCategory":{"properties":{"name":{"type":"string","title":"Name"},"group":{"type":"string","enum":["Site","Content","Support","Other"],"title":"Group"}},"type":"object","required":["name","group"],"title":"AuditPageCategory"},"AuditProgress":{"properties":{"phase":{"type":"string","enum":["discovering","reading","judging","done","failed"],"title":"Phase"},"found":{"type":"integer","title":"Found"},"read":{"type":"integer","title":"Read"},"planned":{"type":"integer","title":"Planned"},"shots":{"type":"integer","title":"Shots"}},"type":"object","required":["phase","found","read","planned","shots"],"title":"AuditProgress"},"AuditTone":{"properties":{"formality":{"type":"string","enum":["formal","conversational"],"title":"Formality"},"complexity":{"type":"string","enum":["technical","plain"],"title":"Complexity"}},"additionalProperties":false,"type":"object","required":["formality","complexity"],"title":"AuditTone"},"AutonomyAreaRow":{"properties":{"area":{"type":"string","enum":["website","content","outreach"],"title":"Area"},"switches":{"$ref":"#/components/schemas/AutonomySwitches"},"unavailable":{"items":{"type":"string","enum":["picks_up_work","runs_steps","skips_draft_approval","acts_without_asking"]},"type":"array","title":"Unavailable"},"suspended":{"type":"boolean","title":"Suspended"},"refusal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refusal"},"outreach":{"anyOf":[{"$ref":"#/components/schemas/OutreachLimitResponse"},{"type":"null"}]}},"type":"object","required":["area","switches","unavailable","suspended","refusal","outreach"],"title":"AutonomyAreaRow","description":"One area of work on the Autonomy page: what is stored, which cells the\ngrid disables, and the area's extras."},"AutonomyPayload":{"properties":{"preset":{"type":"string","enum":["autopilot","delegate","ask_first","manual","custom"],"title":"Preset"},"locked":{"items":{"type":"string","enum":["picks_up_work","runs_steps","skips_draft_approval","acts_without_asking"]},"type":"array","title":"Locked"},"locked_presets":{"items":{"type":"string","enum":["autopilot","delegate","ask_first","manual","custom"]},"type":"array","title":"Locked Presets"},"areas":{"items":{"$ref":"#/components/schemas/AutonomyAreaRow"},"type":"array","title":"Areas"},"read_only":{"anyOf":[{"$ref":"#/components/schemas/AutonomyReadOnly"},{"type":"null"}]},"simple":{"anyOf":[{"$ref":"#/components/schemas/AutonomySimple"},{"type":"null"}]},"site_fixes_executor":{"type":"boolean","title":"Site Fixes Executor"}},"type":"object","required":["preset","locked","locked_presets","areas","read_only","simple","site_fixes_executor"],"title":"AutonomyPayload","description":"A brand's Autonomy as the page draws it: the two switches, the preset,\nthe 3 x 4 grid, and what the plan locks."},"AutonomyReadOnly":{"properties":{"reason":{"type":"string","enum":["canceled","grace_lapsed","archived","no_plan"],"title":"Reason"},"until":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Until"},"message":{"type":"string","title":"Message"}},"type":"object","required":["reason","until","message"],"title":"AutonomyReadOnly","description":"Why the plan refuses Autonomy writes, so the page disables the controls\nand says so rather than meeting 402 `no_plan` on a click."},"AutonomySimple":{"properties":{"ask_before_leaving":{"type":"boolean","title":"Ask Before Leaving"},"auto_site_fixes":{"type":"boolean","title":"Auto Site Fixes"}},"type":"object","required":["ask_before_leaving","auto_site_fixes"],"title":"AutonomySimple","description":"The two switches the Autonomy page opens on (#3295). Each combination\nwrites the grid `SWITCHES_BY_SIMPLE` names."},"AutonomySwitches":{"properties":{"picks_up_work":{"type":"boolean","title":"Picks Up Work"},"runs_steps":{"type":"boolean","title":"Runs Steps"},"skips_draft_approval":{"type":"boolean","title":"Skips Draft Approval"},"acts_without_asking":{"type":"boolean","title":"Acts Without Asking"}},"additionalProperties":false,"type":"object","required":["picks_up_work","runs_steps","skips_draft_approval","acts_without_asking"],"title":"AutonomySwitches","description":"One area's four switches, each a rung of one ladder (D16)."},"AxisPanePart":{"properties":{"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value","description":"This part's figure, from 0 to 100, or null if unmeasured."},"numerator":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Numerator","description":"The measured positive count or sum in this part."},"denominator":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Denominator","description":"The answers or pages measured for this part."}},"type":"object","required":["value","numerator","denominator"],"title":"AxisPanePart"},"AxisPaneParts":{"properties":{"ai_answers":{"$ref":"#/components/schemas/AxisPanePart","description":"The AI answers naming the brand."},"web_pages":{"$ref":"#/components/schemas/AxisPanePart","description":"The pages naming the brand that AI cited or Google ranked."}},"type":"object","required":["ai_answers","web_pages"],"title":"AxisPaneParts"},"AxisQuestion":{"properties":{"prompt_uid":{"type":"string","format":"uuid","title":"Prompt Uid","description":"The stable tracked question identifier."},"text":{"type":"string","title":"Text","description":"The tracked wording."},"figure":{"$ref":"#/components/schemas/Figure","description":"The measured value and comparison; weekly history is included when with_trend is true."}},"type":"object","required":["prompt_uid","text","figure"],"title":"AxisQuestion"},"AxisQuote":{"properties":{"quote":{"type":"string","title":"Quote"},"engine_id":{"type":"string","title":"Engine Id"},"prompt_text":{"type":"string","title":"Prompt Text"},"answer_read_id":{"type":"string","title":"Answer Read Id"},"language":{"type":"string","title":"Language","default":"unknown"},"asked_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asked Language"}},"type":"object","required":["quote","engine_id","prompt_text","answer_read_id","language","asked_language"],"title":"AxisQuote"},"BestPlacement":{"properties":{"industry":{"type":"string","title":"Industry"},"market":{"type":"string","title":"Market"},"path":{"type":"string","title":"Path"},"rank":{"type":"integer","title":"Rank"},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score"}},"type":"object","required":["industry","market","path","rank","score"],"title":"BestPlacement"},"BestQuote":{"properties":{"asked_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asked Language","description":"The language the engine was asked in; null when unknown."},"language":{"type":"string","title":"Language","description":"The content’s language code, or unknown when undetermined.","default":"unknown"},"quote":{"type":"string","title":"Quote","description":"A verbatim passage from the measured evidence."},"engine_id":{"type":"string","title":"Engine Id","description":"The engine that supplied the answer."},"prompt_uid":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Prompt Uid","description":"The stored question identifier; null when this evidence has no linked question."},"prompt_text":{"type":"string","title":"Prompt Text","description":"The question’s wording."},"answer_read_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Answer Read Id","description":"The stored answer identifier that opens this quotation; null when unavailable."}},"type":"object","required":["asked_language","language","quote","engine_id","prompt_uid","prompt_text","answer_read_id"],"title":"BestQuote"},"Blocker":{"properties":{"kind":{"type":"string","enum":["bot_blocked","noindex","not_server_rendered","error_or_challenge"],"title":"Kind"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"detail":{"type":"string","title":"Detail"},"fix":{"type":"string","title":"Fix"},"bots":{"items":{"type":"string"},"type":"array","title":"Bots"},"urls":{"items":{"type":"string"},"type":"array","title":"Urls"}},"type":"object","required":["kind","url","detail","fix","bots","urls"],"title":"Blocker","description":"One thing stopping AI engines reading a page, or the whole site."},"BrandCitationSummary":{"properties":{"brand_citing_domain_count":{"type":"integer","minimum":0.0,"title":"Brand Citing Domain Count","description":"Cited domains naming the brand, including unread-page verdicts."},"total_distinct_domain_count":{"type":"integer","minimum":0.0,"title":"Total Distinct Domain Count","description":"Distinct cited domains in the scan."},"brand_citing_domain_share_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Brand Citing Domain Share Pct"},"unique_third_party_source_count":{"type":"integer","minimum":0.0,"title":"Unique Third Party Source Count","description":"Brand-naming domains outside owned, competitor and unclassified tiers."},"verified_third_party_citing_count":{"type":"integer","minimum":0.0,"title":"Verified Third Party Citing Count","description":"Read domains outside the owned tier whose pages name the brand."},"verified_third_party_total_count":{"type":"integer","minimum":0.0,"title":"Verified Third Party Total Count","description":"All read domains outside the owned tier."},"verified_third_party_citing_share_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Verified Third Party Citing Share Pct"},"owned_share_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Owned Share Pct","description":"Owned sites' share of all citations, rounded half up."},"competitor_share_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Competitor Share Pct","description":"Rival-owned sites' share of all citations, rounded half up."},"independent_share_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Independent Share Pct","description":"Share of all citations outside owned and competitor tiers, rounded half up."},"total_citation_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Total Citation Count","description":"All citation occurrences in the scan."},"read_citation_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Read Citation Count","description":"Citations whose pages were read."},"could_not_read_citation_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Could Not Read Citation Count","description":"Citations whose pages could not be read."},"not_checked_citation_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Not Checked Citation Count","description":"Citations whose pages were not checked."}},"type":"object","required":["brand_citing_domain_count","total_distinct_domain_count","brand_citing_domain_share_pct","unique_third_party_source_count","verified_third_party_citing_count","verified_third_party_total_count","verified_third_party_citing_share_pct","owned_share_pct","competitor_share_pct","independent_share_pct","total_citation_count","read_citation_count","could_not_read_citation_count","not_checked_citation_count"],"title":"BrandCitationSummary","description":"Scan-wide citation counts, each pair over its own domain population.\n\nNothing here is interchangeable, and the counts are not one ladder: a\nsentence quoting any of these states which population it counts, because a\nreader can see two of them side by side.\n\n- ``total_distinct_domain_count`` / ``brand_citing_domain_count``: every\n  distinct domain a citation carries, and the ones naming the brand. No\n  tier or readability filter, so the brand side mixes page-content facts\n  with a model's guess about pages nobody opened. This is the total the\n  Sources section's tier rollups partition, and the\n  ``source_relationship`` claim row count.\n- ``verified_third_party_total_count`` /\n  ``verified_third_party_citing_count``: domains outside the owned tier\n  that the fetcher opened. Page-content facts throughout, the pair\n  ``_source_coverage`` weighs, and so the only one the score disclosure\n  and the score tile may quote.\n- ``unique_third_party_source_count``: brand-citing domains outside the\n  owned, competitor AND unclassified tiers, with no readability filter —\n  a different cut, not a rung between the two pairs above, and it can be\n  smaller than the verified count.\n\nThe answers citing the brand's own pages and the pages naming it are the\nreport's ``answers_citing_you`` and ``sources_mentioning_you``\n(`app.scans.scoring.standing`), not counts here."},"BrandDetail":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"path":{"type":"string","title":"Path"},"facts":{"$ref":"#/components/schemas/BrandFacts"},"measured_markets":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object","title":"Measured Markets"},"best_three":{"items":{"$ref":"#/components/schemas/BrandPlacement"},"type":"array","title":"Best Three"},"placements":{"$ref":"#/components/schemas/PlacementsRead"},"engine_ranks":{"$ref":"#/components/schemas/EngineRanksRead"},"questions":{"$ref":"#/components/schemas/BrandQuestionsRead"},"highlights":{"$ref":"#/components/schemas/HighlightsRead"},"sources":{"$ref":"#/components/schemas/DetailSourcesRead"},"history_series":{"$ref":"#/components/schemas/DetailHistorySeriesRead"}},"type":"object","required":["meta","path","facts","measured_markets","best_three","placements","engine_ranks","questions","highlights","sources","history_series"],"title":"BrandDetail"},"BrandFact":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"statement":{"type":"string","maxLength":300,"minLength":1,"title":"Statement"},"version":{"type":"integer","minimum":1.0,"title":"Version"},"added_by":{"type":"string","format":"uuid","title":"Added By"},"added_at":{"type":"string","format":"date-time","title":"Added At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"source":{"anyOf":[{"$ref":"#/components/schemas/FactSource"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string","enum":["company","number","audience","offer","category","opinion"]},{"type":"null"}],"title":"Kind","description":"The interpreted claim's kind; null while interpretation is pending."},"check":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Check","description":"The comparison in words, preserving scope, time, units and qualifiers; null for simple agreement or an opinion."},"question":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Question","description":"A probe explicitly naming the brand in its Default segment's language; null for an opinion or pending interpretation."},"definition_version":{"type":"integer","minimum":1.0,"title":"Definition Version","description":"The version of the statement, kind, comparison and probe definition.","default":1},"earlier_wordings":{"items":{"type":"string"},"type":"array","title":"Earlier Wordings","description":"Earlier wordings of this definition version, kept across a wording fix so its readings, including those stored before definitions were versioned, stay counted."},"suggestion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Suggestion","description":"What to track instead of an unmeasurable opinion; null for a measurable or uninterpreted fact."},"added_by_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Added By Name","description":"The original author's current display name; null when the account is unavailable."},"split_candidates":{"items":{"$ref":"#/components/schemas/FactDefinition"},"type":"array","title":"Split Candidates","description":"Suggested separate facts for a compound statement; the original stays measured as written until a member confirms the split."},"interpretation_failed":{"type":"boolean","title":"Interpretation Failed","description":"Interpretation could not complete because its provider was unavailable.","default":false}},"type":"object","required":["id","statement","version","added_by","added_at","updated_at","source","kind","check","question","definition_version","earlier_wordings","suggestion","added_by_name","split_candidates","interpretation_failed"],"title":"BrandFact"},"BrandFacts":{"properties":{"brand_id":{"type":"string","format":"uuid","title":"Brand Id"},"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases"},"hq_country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hq Country"},"audience":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audience"},"parent_brand_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Brand Id"}},"type":"object","required":["brand_id","name","slug","domain","aliases","hq_country","audience","parent_brand_id"],"title":"BrandFacts"},"BrandLookRead":{"properties":{"website_look_found":{"type":"boolean","title":"Website Look Found","description":"Whether the brand has a stored website look available to reset to."},"files":{"additionalProperties":{"$ref":"#/components/schemas/FileStatus"},"propertyNames":{"enum":["logo","logo_dark","heading_font","body_font"]},"type":"object","title":"Files","description":"Processing status and failure code for each logo and font slot."},"colors":{"$ref":"#/components/schemas/LookColors","description":"The four colours of the applied graphics identity."},"heading_font":{"$ref":"#/components/schemas/LookFontRead","description":"Heading font family and source."},"body_font":{"$ref":"#/components/schemas/LookFontRead","description":"Body font family and source."},"has_logo":{"type":"boolean","title":"Has Logo","description":"Whether the applied identity has a logo.","default":false},"has_dark_logo":{"type":"boolean","title":"Has Dark Logo","description":"Whether the applied identity has a logo for dark backgrounds.","default":false},"default_social_card_style":{"type":"string","enum":["mounted","strip","band"],"title":"Default Social Card Style","description":"Brand default social card layout.","default":"mounted"},"style_cards":{"items":{"$ref":"#/components/schemas/StyleCardRead"},"type":"array","title":"Style Cards","description":"A preview card for each available layout."},"edited_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Edited At","description":"Latest member save time; null while following the website look."}},"type":"object","required":["website_look_found","files","colors","heading_font","body_font","has_logo","has_dark_logo","default_social_card_style","style_cards","edited_at"],"title":"BrandLookRead"},"BrandPlacement":{"properties":{"filters":{"$ref":"#/components/schemas/LeaderboardFilters"},"path":{"type":"string","title":"Path"},"title":{"type":"string","title":"Title"},"brand":{"$ref":"#/components/schemas/BrandRow"},"sides":{"anyOf":[{"$ref":"#/components/schemas/PlacementSides"},{"type":"null"}]}},"type":"object","required":["filters","path","title","brand","sides"],"title":"BrandPlacement"},"BrandProductCards":{"properties":{"weeks":{"type":"integer","title":"Weeks","description":"Weekly reports counted from the period measured as ecommerce.","default":0},"state":{"type":"string","enum":["read","not_read","not_measured"],"title":"State","description":"Whether the population's product cards were read."},"in_product_cards":{"$ref":"#/components/schemas/ShoppingShare","description":"Answers showing the brand divided by answers with organic cards."},"average_position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Position","description":"Mean of each answer's best place for the brand."},"best_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Position","description":"Lowest organic place for the brand."}},"type":"object","required":["weeks","state","in_product_cards","average_position","best_position"],"title":"BrandProductCards"},"BrandProfile":{"properties":{"sells_to":{"type":"string","enum":["businesses","consumers"],"title":"Sells To","description":"Who the brand sells to: `businesses` or `consumers`.","default":"businesses"},"ecommerce":{"type":"boolean","title":"Ecommerce","description":"Whether the brand is measured as ecommerce, a brand selling goods online, which reads its products, sellers and prices and asks no customer size or service area.","default":false},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"audience":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audience"},"offering":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offering"},"differentiators":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Differentiators"},"customer_size":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"Customer Size"},"service_area":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"Service Area"},"use_cases":{"items":{"type":"string","maxLength":160,"minLength":1},"type":"array","maxItems":5,"title":"Use Cases"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"product_lines":{"items":{"$ref":"#/components/schemas/ProductLineView"},"type":"array","title":"Product Lines"},"measured_product_line":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Measured Product Line"},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases"},"tone":{"$ref":"#/components/schemas/BrandTone"},"moving_away_from":{"items":{"type":"string"},"type":"array","title":"Moving Away From","description":"Labels the brand no longer wants to be described by."}},"type":"object","required":["sells_to","ecommerce","category","audience","offering","differentiators","customer_size","service_area","use_cases","country","product_lines","measured_product_line","aliases","tone","moving_away_from"],"title":"BrandProfile"},"BrandProfilePage":{"properties":{"domain_id":{"type":"string","title":"Domain Id"},"domain":{"type":"string","title":"Domain"},"profile":{"$ref":"#/components/schemas/BrandProfile"},"countries":{"additionalProperties":{"type":"string"},"type":"object","title":"Countries"},"edited_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Edited At"},"claims":{"items":{"$ref":"#/components/schemas/ProfileClaim"},"type":"array","title":"Claims"},"facts":{"items":{"$ref":"#/components/schemas/BrandFact"},"type":"array","title":"Facts"},"fact_limit":{"type":"integer","title":"Fact Limit","default":20},"next_fact_check_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Fact Check At","description":"The brand's next weekly report date, when scheduled."},"brand_paused":{"type":"boolean","title":"Brand Paused","description":"Whether the brand's checks are paused.","default":false},"aliases":{"items":{"$ref":"#/components/schemas/AliasRow"},"type":"array","title":"Aliases"},"alias_limit":{"type":"integer","title":"Alias Limit"},"review_profile_urls":{"items":{"$ref":"#/components/schemas/ReviewProfileUrl"},"type":"array","title":"Review Profile Urls"},"rivals":{"items":{"$ref":"#/components/schemas/RivalTag"},"type":"array","title":"Rivals"},"rival_cap":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rival Cap"},"personas":{"items":{"$ref":"#/components/schemas/PersonaBox"},"type":"array","title":"Personas"}},"type":"object","required":["domain_id","domain","profile","countries","edited_at","claims","facts","fact_limit","next_fact_check_at","brand_paused","aliases","alias_limit","review_profile_urls","rivals","rival_cap","personas"],"title":"BrandProfilePage","description":"The configuration page, whole. No band and no score: nothing here is a\nmeasurement, and everything here decides one."},"BrandProfileResponse":{"properties":{"brand_name":{"type":"string","title":"Brand Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"category":{"type":"string","title":"Category"},"target_buyer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Buyer"},"differentiator":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Differentiator"},"customer_size":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"Customer Size"},"service_area":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"Service Area"},"use_cases":{"items":{"type":"string","maxLength":160,"minLength":1},"type":"array","maxItems":5,"title":"Use Cases"},"competitors":{"items":{"type":"string"},"type":"array","title":"Competitors"},"competitor_domains":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object","title":"Competitor Domains"},"category_leader":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category Leader"},"tone":{"$ref":"#/components/schemas/BrandTone"},"ecommerce_categories":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Ecommerce Categories"},"top_product_pages":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Top Product Pages"},"product_lines":{"items":{"$ref":"#/components/schemas/ProductLineResponse"},"type":"array","title":"Product Lines"},"measured_product_line":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Measured Product Line"},"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market"}},"type":"object","required":["brand_name","description","category","target_buyer","differentiator","customer_size","service_area","use_cases","competitors","competitor_domains","category_leader","tone","ecommerce_categories","top_product_pages","product_lines","measured_product_line","market"],"title":"BrandProfileResponse"},"BrandQuestion":{"properties":{"filters":{"$ref":"#/components/schemas/LeaderboardFilters"},"path":{"type":"string","title":"Path"},"title":{"type":"string","title":"Title"},"prompt_id":{"type":"string","format":"uuid","title":"Prompt Id"},"text":{"type":"string","title":"Text"},"language":{"type":"string","title":"Language"},"place":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Place"},"competitors":{"items":{"$ref":"#/components/schemas/QuestionCompetitor"},"type":"array","title":"Competitors"}},"type":"object","required":["filters","path","title","prompt_id","text","language","place","competitors"],"title":"BrandQuestion"},"BrandQuestionsRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"withheld":{"items":{"type":"integer"},"type":"array","title":"Withheld","description":"Ranks present in the module whose rows are withheld."},"rows":{"items":{"$ref":"#/components/schemas/BrandQuestion"},"type":"array","title":"Rows"}},"type":"object","required":["meta","next_cursor","total","limit","offset","withheld","rows"],"title":"BrandQuestionsRead"},"BrandRow":{"properties":{"brand_id":{"type":"string","format":"uuid","title":"Brand Id"},"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"hq_country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hq Country"},"audience":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audience"},"figures":{"$ref":"#/components/schemas/Figures"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"},"previous_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Previous Rank"},"rank_change":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank Change","description":"Previous rank minus current rank; positive means a rise."},"state":{"anyOf":[{"type":"string","enum":["new","returning","unranked"]},{"type":"null"}],"title":"State"},"score_series":{"items":{"$ref":"#/components/schemas/RankScorePoint"},"type":"array","title":"Score Series"},"placements":{"items":{"$ref":"#/components/schemas/Placement"},"type":"array","title":"Placements"},"medals":{"$ref":"#/components/schemas/Medals"},"sides":{"anyOf":[{"$ref":"#/components/schemas/PlacementSides"},{"type":"null"}]},"strength":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Strength"},"change_state":{"type":"string","enum":["up","down","steady","calibrating","first_report","not_comparable"],"title":"Change State"},"mentioned_by":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Mentioned By"},"recommended_by":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Recommended By"},"engines":{"additionalProperties":{"$ref":"#/components/schemas/EngineFigures"},"type":"object","title":"Engines"}},"type":"object","required":["brand_id","name","slug","domain","hq_country","audience","figures","rank","previous_rank","rank_change","state","score_series","placements","medals","sides","strength","change_state","mentioned_by","recommended_by","engines"],"title":"BrandRow"},"BrandTone":{"properties":{"formality":{"anyOf":[{"type":"string","enum":["formal","conversational"]},{"type":"null"}],"title":"Formality"},"complexity":{"anyOf":[{"type":"string","enum":["technical","plain"]},{"type":"null"}],"title":"Complexity"}},"type":"object","required":["formality","complexity"],"title":"BrandTone","description":"How a brand's pages sound to the reader. A write replaces both fields, and\nnull clears one."},"BrandsRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"rows":{"items":{"$ref":"#/components/schemas/BrandRow"},"type":"array","title":"Rows"}},"type":"object","required":["meta","next_cursor","total","limit","offset","rows"],"title":"BrandsRead"},"ChangeFilters":{"properties":{"engine":{"type":"string","title":"Engine","description":"Engine whose answers changed."},"prompt":{"type":"string","title":"Prompt","description":"Prompt UUID when the change concerns one prompt."},"topic":{"type":"string","title":"Topic","description":"Topic under which the change was observed."}},"type":"object","required":["engine","prompt","topic"],"title":"ChangeFilters"},"CitationMetric":{"properties":{"count":{"type":"integer","minimum":0.0,"title":"Count"},"of":{"type":"integer","minimum":0.0,"title":"Of"},"pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Pct"}},"type":"object","required":["count","of","pct"],"title":"CitationMetric","description":"One of the two citation metrics over one read: the count, the\npopulation it is out of, and its share in points, null where that\npopulation is empty."},"CitationSourceLink":{"properties":{"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"}},"type":"object","required":["url","title"],"title":"CitationSourceLink"},"CitedPage":{"properties":{"language":{"type":"string","title":"Language","default":"unknown"},"url":{"type":"string","title":"Url"},"document_key":{"type":"string","title":"Document Key"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"domain":{"type":"string","title":"Domain"}},"type":"object","required":["language","url","document_key","title","domain"],"title":"CitedPage"},"CitedShare":{"properties":{"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value"},"citing_answers":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Citing Answers"},"answers":{"type":"integer","title":"Answers"},"state":{"type":"string","enum":["measured","unavailable","not_measured"],"title":"State"}},"type":"object","required":["value","citing_answers","answers","state"],"title":"CitedShare"},"ClaimRow":{"properties":{"insight":{"anyOf":[{"$ref":"#/components/schemas/ServedInsight"},{"type":"null"}],"description":"An actionable page insight for this claim, preferring existing work. The reputation page serves it; other reads can omit the recommendation."},"key":{"type":"string","title":"Key","description":"The stable subject key used to open its detail read."},"kind":{"type":"string","enum":["category","audience","offer","difference","fact"],"title":"Kind","description":"The subject’s served kind."},"wording":{"type":"string","title":"Wording","description":"The claim wording the selected answers were measured against."},"quote":{"anyOf":[{"$ref":"#/components/schemas/QuotedLine"},{"type":"null"}],"description":"A verbatim passage from the measured evidence."},"verdicts":{"$ref":"#/components/schemas/Verdicts","description":"Answer counts for each agreement verdict."},"origins":{"anyOf":[{"$ref":"#/components/schemas/FactOrigins"},{"type":"null"}],"description":"A fact's verdict counts split by origin: its own question or tracked prompts. Null for a profile claim."},"definition_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Definition Version","description":"The fact definition version the counts were read against; null for a profile claim or for readings from before definitions were versioned."},"current_version_pending":{"type":"boolean","title":"Current Version Pending","description":"The fact was edited to a new definition no report has read yet; the counts are of the version named in definition_version.","default":false},"trend":{"$ref":"#/components/schemas/ClaimTrend","description":"The comparison with the earlier measured period."},"state":{"anyOf":[{"$ref":"#/components/schemas/ClaimState"},{"type":"null"}],"description":"The served measurement or work state."},"parts":{"items":{"$ref":"#/components/schemas/StatementPart"},"type":"array","title":"Parts","description":"A profile statement's parts, where the latest report measured Understood part by part; empty for a fact or a statement measured whole."}},"type":"object","required":["insight","key","kind","wording","quote","verdicts","origins","definition_version","current_version_pending","trend","state","parts"],"title":"ClaimRow"},"ClaimState":{"properties":{"kind":{"type":"string","enum":["new","action","resolved"],"title":"Kind","description":"The subject’s served kind."},"label":{"type":"string","title":"Label","description":"The display name."},"action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Action Id","description":"The related work item identifier, or null when none exists."}},"type":"object","required":["kind","label","action_id"],"title":"ClaimState"},"ClaimTrend":{"properties":{"state":{"type":"string","enum":["up","down","steady","calibrating","first_report","not_comparable","none"],"title":"State","description":"The served measurement or work state."},"delta":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Delta","description":"The signed change from the earlier comparable measurement; null without a comparison."},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"The words shown beside the trend, or null without a measurement."},"definition_changed":{"type":"boolean","title":"Definition Changed","description":"The comparison crosses an edit that changed the fact's meaning, so no change is shown across it.","default":false}},"type":"object","required":["state","delta","label","definition_changed"],"title":"ClaimTrend","description":"The change in the share of answers that contradict a claim, as the\nTrend column states it: a rise is bad."},"ComparabilityKey":{"properties":{"engines":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Engines"},"markets":{"additionalProperties":{"type":"string"},"type":"object","title":"Markets","default":{}},"score_version":{"type":"string","title":"Score Version"},"answer_pack_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Answer Pack Version"},"passes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Passes"},"sides":{"anyOf":[{"items":{"type":"string","enum":["ai","search"]},"type":"array"},{"type":"null"}],"title":"Sides"},"keyword_set_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Keyword Set Hash"},"understood_measure":{"anyOf":[{"type":"string","enum":["statements","parts"]},{"type":"null"}],"title":"Understood Measure","description":"How the report read Understood: each profile statement whole, or part by part. Only Understood's trend and change compare it; null where unknown."},"sells_to":{"anyOf":[{"type":"string","enum":["businesses","consumers"]},{"type":"null"}],"title":"Sells To","description":"Who the run measured the brand as selling to. A change starts a new series; null where unknown."},"ecommerce":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ecommerce","description":"Whether the run measured the brand as ecommerce. A change never breaks a series; null where unknown."},"shopping_pack_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Shopping Pack Version","description":"The version of the reading that judged the report's product cards. Only product card figures compare it; null where the report read no product cards."}},"type":"object","required":["engines","markets","score_version","answer_pack_version","passes","sides","keyword_set_hash","understood_measure","sells_to","ecommerce","shopping_pack_version"],"title":"ComparabilityKey","description":"The instrument one read was taken with. A part that cannot be told is\nNone, and a None part never breaks a series: a run whose answers the\nretention sweep took no longer says which engines it asked."},"ComparisonPeriod":{"properties":{"reports":{"type":"integer","title":"Reports"},"first_answer_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Answer At"},"last_answer_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Answer At"}},"type":"object","required":["reports","first_answer_at","last_answer_at"],"title":"ComparisonPeriod"},"CompetitorBoard":{"properties":{"rows":{"items":{"$ref":"#/components/schemas/CompetitorRow"},"type":"array","title":"Rows"},"total":{"type":"integer","title":"Total"},"offset":{"type":"integer","title":"Offset"},"limit":{"type":"integer","title":"Limit"},"sort":{"type":"string","title":"Sort","description":"The selected sort column, echoed from the request.","x-extensible-enum":["brand","score","trend","mentioned","recommended","product_cards"]},"direction":{"type":"string","enum":["asc","desc"],"title":"Direction"}},"type":"object","required":["rows","total","offset","limit","sort","direction"],"title":"CompetitorBoard","description":"One page of the leaderboard, sorted as asked. `total` is every row."},"CompetitorCitedPage":{"properties":{"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"citations":{"type":"integer","title":"Citations"}},"type":"object","required":["url","title","citations"],"title":"CompetitorCitedPage"},"CompetitorContentEvidenceSection":{"properties":{"status":{"type":"string","enum":["ready","unavailable"],"title":"Status"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"competitors":{"items":{"$ref":"#/components/schemas/CompetitorContentGroup"},"type":"array","title":"Competitors"}},"additionalProperties":false,"type":"object","required":["status","message","competitors"],"title":"CompetitorContentEvidenceSection"},"CompetitorContentGroup":{"properties":{"competitor":{"type":"string","title":"Competitor"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"is_unlisted":{"type":"boolean","title":"Is Unlisted","default":false},"total_citations":{"type":"integer","minimum":0.0,"title":"Total Citations","default":0},"total_pages":{"type":"integer","minimum":0.0,"title":"Total Pages","default":0},"pages":{"items":{"$ref":"#/components/schemas/CompetitorContentPage"},"type":"array","title":"Pages"}},"type":"object","required":["competitor","domain","is_unlisted","total_citations","total_pages","pages"],"title":"CompetitorContentGroup"},"CompetitorContentPage":{"properties":{"url":{"type":"string","title":"Url"},"page_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Title"},"citation_count":{"type":"integer","minimum":0.0,"title":"Citation Count","description":"Citation occurrences of this page or source in the scan."},"distinct_queries":{"type":"integer","minimum":0.0,"title":"Distinct Queries"},"distinct_engines":{"type":"integer","minimum":0.0,"title":"Distinct Engines"},"supported_topics":{"items":{"type":"string"},"type":"array","title":"Supported Topics"},"claim_summary":{"type":"string","title":"Claim Summary"},"sample_queries":{"items":{"type":"string"},"type":"array","maxItems":3,"title":"Sample Queries"},"sample_engines":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Sample Engines"},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type"},"content_type_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type Label"}},"type":"object","required":["url","page_title","citation_count","distinct_queries","distinct_engines","supported_topics","claim_summary","sample_queries","sample_engines","content_type","content_type_label"],"title":"CompetitorContentPage"},"CompetitorEngine":{"properties":{"key":{"type":"string","title":"Key","description":"The figure, prompt or engine key."},"label":{"type":"string","title":"Label","description":"The display name of the figure, prompt or engine."},"them":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Them","description":"The competitor's value, or null when unmeasured."},"you":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"You","description":"Your brand's value, or null when unmeasured."},"gap":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Gap","description":"Your value minus the competitor's, or null if either is unmeasured."},"lead":{"anyOf":[{"type":"string","enum":["you","them","level"]},{"type":"null"}],"title":"Lead","description":"Which brand leads, or null if either is unmeasured."},"change":{"anyOf":[{"$ref":"#/components/schemas/FigureChange"},{"type":"null"}],"description":"The competitor's Heralded Score change on this engine."}},"type":"object","required":["key","label","them","you","gap","lead","change"],"title":"CompetitorEngine"},"CompetitorRow":{"properties":{"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"},"product_cards":{"anyOf":[{"$ref":"#/components/schemas/BrandProductCards"},{"type":"null"}],"description":"Organic product-card share and positions; null for B2B or Search."},"brand_key":{"type":"string","title":"Brand Key"},"brand_name":{"type":"string","title":"Brand Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"is_you":{"type":"boolean","title":"Is You"},"score":{"$ref":"#/components/schemas/ScoreMark"},"trend":{"$ref":"#/components/schemas/PromptTrend"},"mentioned":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentioned"},"recommended":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Recommended"},"mentioned_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Mentioned Since","description":"Start of a shorter AI measurement population within the selected period."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"The latest stored AI description."}},"type":"object","required":["rank","product_cards","brand_key","brand_name","domain","is_you","score","trend","mentioned","recommended","mentioned_since","description"],"title":"CompetitorRow","description":"A tracked brand ranked by the selected side's figure, with ties sharing a place."},"CompetitorStanding":{"properties":{"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank","description":"Place by score among tracked brands."},"brand_key":{"type":"string","title":"Brand Key","description":"The competitor key, as listCompetitors names it."},"brand_name":{"type":"string","title":"Brand Name","description":"The brand's name."},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"The brand's site, when known."},"is_you":{"type":"boolean","title":"Is You","description":"True on the brand's own row."},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score","description":"The Heralded Score."},"change":{"type":"string","enum":["up","down","steady","not_comparable","calibrating","new","none"],"title":"Change","description":"The paired test's verdict on the score's move."},"delta":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Delta","description":"The score's move in whole points."},"mentioned":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentioned","description":"Whole percent of answers naming the brand."},"recommended":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Recommended","description":"Whole percent of answers recommending it."}},"type":"object","required":["rank","brand_key","brand_name","domain","is_you","score","change","delta","mentioned","recommended"],"title":"CompetitorStanding"},"Competitors":{"properties":{"state":{"type":"string","enum":["ready","missing","not_set"],"title":"State","description":"ready, or missing when no score was measured."},"rows":{"items":{"$ref":"#/components/schemas/CompetitorStanding"},"type":"array","title":"Rows","description":"By rank."}},"type":"object","required":["state","rows"],"title":"Competitors"},"CompetitorsPage":{"properties":{"period":{"$ref":"#/components/schemas/PeriodDescriptor"},"share_of_voice":{"$ref":"#/components/schemas/VoiceBox"},"leaderboard":{"$ref":"#/components/schemas/CompetitorBoard"},"capacity":{"$ref":"#/components/schemas/RosterPool"},"checked_7d":{"type":"integer","title":"Checked 7D","description":"Tracked competitors whose website Herald checked in the last seven days."},"discovered":{"$ref":"#/components/schemas/DiscoveredPage"},"channels":{"$ref":"#/components/schemas/DiscoveredPage"}},"type":"object","required":["period","share_of_voice","leaderboard","capacity","checked_7d","discovered","channels"],"title":"CompetitorsPage"},"CompletedWork":{"properties":{"action_id":{"type":"string","format":"uuid","title":"Action Id","description":"The action, as getAction reads it."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"What the work delivered."},"issue_type":{"anyOf":[{"$ref":"#/components/schemas/IssueType"},{"type":"string","enum":["daily_read","deep_read","inventory_crawl","detection_sweep","search_sweep"]}],"title":"Issue Type","description":"The kind of work."},"delivered_at":{"type":"string","format":"date-time","title":"Delivered At","description":"When the work was delivered."},"result":{"type":"string","enum":["Delivered","Cited","Paying off"],"title":"Result","description":"Its result when the report issued."},"result_at":{"type":"string","format":"date-time","title":"Result At","description":"Latest delivery, citation or measured outcome date."}},"type":"object","required":["action_id","title","issue_type","delivered_at","result","result_at"],"title":"CompletedWork"},"ConnectResults":{"properties":{"state":{"type":"string","const":"not_connected","title":"State","description":"The sources are absent, rather than a read failing.","default":"not_connected"},"tone":{"type":"string","const":"neutral","title":"Tone","description":"Missing connections are neutral.","default":"neutral"},"sources":{"items":{"type":"string","enum":["search_console","crawler_visits"]},"type":"array","title":"Sources","description":"Only the missing sources offered for connection."},"summary":{"type":"string","title":"Summary","description":"Offer naming the missing sources."},"label":{"type":"string","title":"Label","description":"Connection control label.","default":"Connect"},"href":{"type":"string","title":"Href","description":"Brand connections settings path."}},"type":"object","required":["state","tone","sources","summary","label","href"],"title":"ConnectResults"},"ConnectionActivityEventRow":{"properties":{"kind":{"type":"string","title":"Kind","description":"The stored event's kind. First occurrences have a first_ prefix."},"at":{"type":"string","format":"date-time","title":"At","description":"When the event happened."},"label":{"type":"string","title":"Label","description":"What happened, in words, distinguishing first occurrences."}},"type":"object","required":["kind","at","label"],"title":"ConnectionActivityEventRow"},"ConnectionActivityRow":{"properties":{"kind":{"anyOf":[{"type":"string","enum":["mailbox_read","email_sent","data_read","crawls_read","report_posted","contacts_synced"]},{"type":"string","const":"checked"}],"title":"Kind","description":"What it did: `mailbox_read`, `email_sent`, `data_read` (search or analytics data), `crawls_read` (crawler counts), `report_posted`, `contacts_synced`, or `checked` for a health check."},"at":{"type":"string","format":"date-time","title":"At","description":"When it did it."}},"type":"object","required":["kind","at"],"title":"ConnectionActivityRow","description":"The newest thing a connection did: a sync, a send, a post or a check."},"ConnectionSetupEventRow":{"properties":{"line":{"type":"string","title":"Line","description":"What happened, in words."},"at":{"type":"string","format":"date-time","title":"At","description":"When it happened."},"tone":{"type":"string","enum":["failure","none"],"title":"Tone","description":"`failure` for a refusal."}},"type":"object","required":["line","at","tone"],"title":"ConnectionSetupEventRow","description":"Something dated that happened at a setup step."},"ConnectionSetupRow":{"properties":{"status":{"type":"string","enum":["working","needs_you","setting_up","not_connected"],"title":"Status","description":"`working`, `needs_you` when a member has something to fix or choose, `setting_up` while it is connected and has not yet done its work for the brand, or `not_connected`."},"steps":{"items":{"$ref":"#/components/schemas/ConnectionSetupStepRow"},"type":"array","title":"Steps","description":"The setup steps in order. Empty for the sitemap, which needs none."}},"type":"object","required":["status","steps"],"title":"ConnectionSetupRow","description":"Where a connection stands for the brand."},"ConnectionSetupStepRow":{"properties":{"key":{"type":"string","title":"Key","description":"The step's stable key, such as `sign_in` or `ready`."},"label":{"type":"string","title":"Label","description":"The step, in words."},"status":{"type":"string","enum":["done","now","ahead"],"title":"Status","description":"`done`, `now` for the step the connection stands at, or `ahead`."},"at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"At","description":"When a done step was first done."},"events":{"items":{"$ref":"#/components/schemas/ConnectionSetupEventRow"},"type":"array","title":"Events","description":"What happened at the step, newest first. Empty unless something went wrong there."}},"type":"object","required":["key","label","status","at","events"],"title":"ConnectionSetupStepRow","description":"One step of setting a connection up."},"ConnectionStatusFactRow":{"properties":{"kind":{"type":"string","enum":["activity","waits_for","problem"],"title":"Kind","description":"The latest activity, a pending first read or choice, or a problem."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Activity kind or problem code. Null while waiting."},"target":{"anyOf":[{"type":"string","x-extensible-enum":["first_read","first_sync","choice","selection"]},{"type":"null"}],"title":"Target","description":"What the connection waits for. Null for activity and problems."},"at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"At","description":"Activity date, failed sitemap report date, or last success for lost access. Null when no true date is stored."},"on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"On","description":"The next weekly report for first_read, or null before onboarding confirms."}},"type":"object","required":["kind","reason","target","at","on"],"title":"ConnectionStatusFactRow"},"ContentLanguagePreview":{"properties":{"language":{"$ref":"#/components/schemas/LanguageCode"},"source":{"type":"string","enum":["auto","member"],"title":"Source","default":"auto"},"locked":{"type":"boolean","title":"Locked"}},"type":"object","required":["language","source","locked"],"title":"ContentLanguagePreview"},"ContentReadCoverage":{"properties":{"covered":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Covered"},"judged":{"type":"integer","title":"Judged"},"total":{"type":"integer","title":"Total"},"open":{"items":{"type":"string"},"type":"array","title":"Open"}},"type":"object","required":["covered","judged","total","open"],"title":"ContentReadCoverage"},"ContentReadFact":{"properties":{"pillar":{"type":"string","title":"Pillar"},"status":{"type":"string","enum":["fail","unmeasured"],"title":"Status"},"detail":{"type":"string","title":"Detail"}},"type":"object","required":["pillar","status","detail"],"title":"ContentReadFact"},"ContentReadMissingTopic":{"properties":{"title":{"type":"string","title":"Title"},"questions":{"items":{"type":"string"},"type":"array","title":"Questions"},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context"},"action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Action"}},"type":"object","required":["title","questions","context","action"],"title":"ContentReadMissingTopic"},"ContentReadPage":{"properties":{"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"page_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Type"},"priority":{"type":"string","enum":["ineligible","unmeasured","answer_gap","substance_gap","ready"],"title":"Priority"},"value":{"type":"number","title":"Value"},"score":{"type":"number","title":"Score"},"facts":{"items":{"$ref":"#/components/schemas/ContentReadFact"},"type":"array","title":"Facts"},"questions":{"items":{"type":"string"},"type":"array","title":"Questions"},"coverage":{"anyOf":[{"$ref":"#/components/schemas/ContentReadCoverage"},{"type":"null"}]},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context"}},"type":"object","required":["url","title","page_type","priority","value","score","facts","questions","coverage","context"],"title":"ContentReadPage"},"ContentReadPillar":{"properties":{"pillar":{"type":"string","enum":["eligible","answers","substance"],"title":"Pillar"},"passed":{"type":"integer","title":"Passed"},"failed":{"type":"integer","title":"Failed"},"unmeasured":{"type":"integer","title":"Unmeasured"}},"type":"object","required":["pillar","passed","failed","unmeasured"],"title":"ContentReadPillar"},"Contributor":{"properties":{"key":{"type":"string","title":"Key","description":"The producer contributing to this operation."},"agent":{"type":"string","enum":["herald","writer","publicist","engineer"],"title":"Agent","description":"The agent doing this part of the work."},"label":{"type":"string","title":"Label","description":"Who is working and what they are doing."},"feeds":{"items":{"type":"string","enum":["home.score","home.todo","home.changes","home.progress","actions.proposed","actions.work","studio.piece","content.topics","content.suggested","content.pages","visibility.score","visibility.prompts","visibility.competitors","answers","sources","perception.figures","perception.positioning","search.score","search.keywords","website.overview","website.ai_access","website.pages","website.map","website.competitors","onboarding.first_read","onboarding.topics","chat","settings.connections","reviews"]},"type":"array","title":"Feeds","description":"Sections receiving this contribution's result."},"status":{"type":"string","title":"Status","description":"The contribution's current work status.","x-extensible-enum":["queued","working","needs_you","waiting","done","failed"]},"stage":{"type":"string","title":"Stage","description":"The report stage: read, score or file."}},"type":"object","required":["key","agent","label","feeds","status","stage"],"title":"Contributor"},"ConversationList":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"conversations":{"items":{"$ref":"#/components/schemas/V1ConversationSummary"},"type":"array","title":"Conversations"}},"type":"object","required":["meta","next_cursor","total","limit","offset","conversations"],"title":"ConversationList","examples":[{"conversations":[],"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"total":0}]},"ConversationObligation":{"properties":{"id":{"type":"string","title":"Id","description":"The obligation's identifier."},"party":{"type":"string","enum":["us","them"],"title":"Party","description":"Who owes it: the brand, or the source."},"kind":{"type":"string","title":"Kind","description":"What kind of thing it is. Read an unknown value as other.","x-extensible-enum":["answer","material","article","publish","place","payment","call","other"]},"what":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"What","description":"What is owed, in one line; null when withheld."},"due_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Due On","description":"When it is due, where known."},"due_source":{"anyOf":[{"type":"string","enum":["given","default","ours"]},{"type":"null"}],"title":"Due Source","description":"Where its date came from."},"status":{"type":"string","enum":["open","settled","dropped"],"title":"Status","description":"Open, settled, or dropped because it no longer applies."},"actionable":{"type":"boolean","title":"Actionable","description":"Open with everything it waits on settled: only these are anybody's move."},"after":{"items":{"type":"string"},"type":"array","title":"After","description":"The obligations that must be settled first."},"waits_on":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Waits On","description":"When an open one that cannot be acted on yet becomes due, in words."},"option_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Option Key","description":"The offer option it holds for; null where it holds for any."},"settled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Settled At","description":"When it settled or dropped."}},"type":"object","required":["id","party","kind","what","due_on","due_source","status","actionable","after","waits_on","option_key","settled_at"],"title":"ConversationObligation","description":"One thing a side owes in the conversation (#9464)."},"ConversationRecipient":{"properties":{"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address","description":"The address the next email goes to; null while none is known."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"The contact's name, where known."},"found_in":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Found In","description":"Where the address was found: `member` for one a member gave, else the kind of page it was read on."},"page_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Url","description":"The page the address was read on."},"refused":{"anyOf":[{"$ref":"#/components/schemas/RecipientRefusal"},{"type":"null"}],"description":"The newest address of this conversation the brand may no longer write to; null when none was refused."},"candidate":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Candidate","description":"A found contact awaiting your choice; it changes nothing until chosen."},"changeable":{"type":"boolean","title":"Changeable","description":"Whether a member may give another address now. A refused address is rejected with 409 `address_suppressed`."},"proposed":{"anyOf":[{"$ref":"#/components/schemas/ProposedContact"},{"type":"null"}],"description":"Another person a reply named to write to: the next email goes to them, and writing to them makes them the recipient. Null where no reply named anyone new."},"written":{"type":"boolean","title":"Written","description":"Whether an email of ours has gone to the task's current recipient, as distinct from `proposed`.","default":false}},"type":"object","required":["address","name","found_in","page_url","refused","candidate","changeable","proposed","written"],"title":"ConversationRecipient","description":"Who the task's emails go to."},"ConversationState":{"properties":{"whose_move":{"anyOf":[{"type":"string","enum":["us","them"]},{"type":"null"}],"title":"Whose Move","description":"`us` while the brand owes an email or something it agreed to, `them` while the task waits on the source; null once closed, or while it waits behind another task to the same contact."},"next_email":{"anyOf":[{"$ref":"#/components/schemas/NextEmail"},{"type":"null"}],"description":"The email of the brand's due next; null when none is."},"wait":{"anyOf":[{"$ref":"#/components/schemas/WaitResponse"},{"type":"null"}],"description":"What the task waits for, the same object a row's `wait` is; null while it waits on nobody."},"step":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Step","description":"The key of the stage of the task's Steps it stands at; null once it settled or stopped."},"missed":{"anyOf":[{"type":"string","enum":["their_date","our_deadline","follow_up"]},{"type":"null"}],"title":"Missed","description":"A date that passed with a follow-up drafted for a member to review or skip: the date they gave, the date they needed something by, or a follow-up of the brand's that fell due."},"recipient":{"anyOf":[{"$ref":"#/components/schemas/ConversationRecipient"},{"type":"null"}],"description":"Who the emails go to; null when withheld."},"obligations":{"items":{"$ref":"#/components/schemas/ConversationObligation"},"type":"array","title":"Obligations","description":"What each side owes: every open obligation and the most recently settled."}},"type":"object","required":["whose_move","next_email","wait","step","missed","recipient","obligations"],"title":"ConversationState","description":"Where the conversation stands, served so no surface works it out\n(#9465)."},"CountryKeyword":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"text":{"type":"string","title":"Text"},"language":{"type":"string","title":"Language"},"volume_state":{"type":"string","title":"Volume State","x-extensible-enum":["pending","measured","unavailable","zero","no_data"]},"searches_mo":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Searches Mo"},"best_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Rank"},"last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Checked At"}},"type":"object","required":["id","text","language","volume_state","searches_mo","best_rank","last_checked_at"],"title":"CountryKeyword"},"DataAsOf":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"completed_at":{"type":"string","format":"date-time","title":"Completed At"}},"type":"object","required":["id","completed_at"],"title":"DataAsOf"},"Decision":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"This issued decision's stable identity."},"action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Action Id","description":"Its stored action, null for a job or removed action."},"job_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Job Id","description":"Its recurring job's work-row identity."},"kind":{"type":"string","enum":["needs_you","suggestion"],"title":"Kind","description":"A member turn or suggested work to start."},"title":{"type":"string","title":"Title","description":"The work's title when the brief issued."},"demand":{"type":"string","title":"Demand","description":"What the decision asks the reader to do."},"href":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Href","description":"The work link, null if the work was removed."},"from_last_week":{"type":"boolean","title":"From Last Week","description":"The same unanswered decision was in the previous brief."},"decided":{"type":"boolean","title":"Decided","description":"A decision has been made, or this request no longer applies."}},"type":"object","required":["id","action_id","job_id","kind","title","demand","href","from_last_week","decided"],"title":"Decision"},"DescribedShare":{"properties":{"value":{"type":"integer","title":"Value"},"low":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Low"},"high":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"High"},"n":{"type":"integer","title":"N"},"change":{"anyOf":[{"$ref":"#/components/schemas/PairedChange"},{"type":"null"}]}},"type":"object","required":["value","low","high","n","change"],"title":"DescribedShare","description":"A weighted share of answers naming the brand, its range and answer count."},"DescribesYou":{"properties":{"understood":{"anyOf":[{"$ref":"#/components/schemas/DescribedShare"},{"type":"null"}]},"praised":{"anyOf":[{"$ref":"#/components/schemas/DescribedShare"},{"type":"null"}]},"n":{"type":"integer","title":"N","description":"Use each figure denominator.","deprecated":true}},"type":"object","required":["understood","praised","n"],"title":"DescribesYou","description":"Understood and Praised over the answers naming the brand that a full\nread interpreted. `n` counts those answers; each share states its own."},"DetailHistoryPoint":{"properties":{"month":{"type":"string","title":"Month"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score"},"state":{"type":"string","enum":["ranked","unranked","missing","not_on_roster"],"title":"State"},"mentioned":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentioned"},"recommended":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Recommended"}},"type":"object","required":["month","rank","score","state","mentioned","recommended"],"title":"DetailHistoryPoint"},"DetailHistorySeries":{"properties":{"filters":{"$ref":"#/components/schemas/LeaderboardFilters"},"path":{"type":"string","title":"Path"},"title":{"type":"string","title":"Title"},"change_state":{"type":"string","enum":["up","down","steady","calibrating","first_report","not_comparable"],"title":"Change State"},"points":{"items":{"$ref":"#/components/schemas/DetailHistoryPoint"},"type":"array","title":"Points"}},"type":"object","required":["filters","path","title","change_state","points"],"title":"DetailHistorySeries"},"DetailHistorySeriesRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"rows":{"items":{"$ref":"#/components/schemas/DetailHistorySeries"},"type":"array","title":"Rows"}},"type":"object","required":["meta","next_cursor","total","limit","offset","rows"],"title":"DetailHistorySeriesRead"},"DetailSource":{"properties":{"filters":{"$ref":"#/components/schemas/LeaderboardFilters"},"source":{"$ref":"#/components/schemas/SourceRow"}},"type":"object","required":["filters","source"],"title":"DetailSource"},"DetailSourcesRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"withheld":{"items":{"type":"integer"},"type":"array","title":"Withheld","description":"Ranks present in the module whose rows are withheld."},"rows":{"items":{"$ref":"#/components/schemas/DetailSource"},"type":"array","title":"Rows"},"mentioned_by":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Mentioned By"},"recommended_by":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Recommended By"}},"type":"object","required":["meta","next_cursor","total","limit","offset","withheld","rows","mentioned_by","recommended_by"],"title":"DetailSourcesRead"},"DiscoveredBrand":{"properties":{"brand_key":{"type":"string","title":"Brand Key"},"brand_name":{"type":"string","title":"Brand Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"is_new":{"type":"boolean","title":"Is New"},"line":{"type":"string","title":"Line"},"score":{"anyOf":[{"$ref":"#/components/schemas/ScoreMark"},{"type":"null"}]},"mentioned":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentioned"},"answers":{"type":"integer","title":"Answers"},"prompts":{"type":"integer","title":"Prompts"}},"type":"object","required":["brand_key","brand_name","domain","is_new","line","score","mentioned","answers","prompts"],"title":"DiscoveredBrand","description":"A brand the answers name that the brand does not track. A channel's\n`score` is null: it is never scored as a competitor."},"DiscoveredPage":{"properties":{"cells":{"items":{"$ref":"#/components/schemas/DiscoveredBrand"},"type":"array","title":"Cells"},"total":{"type":"integer","title":"Total"},"offset":{"type":"integer","title":"Offset"},"limit":{"type":"integer","title":"Limit"}},"type":"object","required":["cells","total","offset","limit"],"title":"DiscoveredPage","description":"One page of Discovered or of Channels, and how many there are."},"DraftGapResponse":{"properties":{"index":{"type":"integer","title":"Index","description":"Its place among the draft's gaps, from 0, in the order they stand."},"label":{"type":"string","title":"Label","description":"What it asks for, as the draft states it."},"kind":{"type":"string","enum":["answer","fact","choose","signature","opt_out"],"title":"Kind","description":"What filling it takes: `answer` an answer the member writes, as its own paragraph; `fact` a fact they supply in its sentence; `choose` their choice on an offer; `signature` the brand's email signature; `opt_out` the sentence for opting out."},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id","description":"The obligation the gap answers (`correspondence.state.obligations`); null for a gap no request asked for."},"target":{"type":"string","enum":["draft","signature"],"title":"Target","description":"Where filling it is saved. draft: the draft's own text; signature: the brand's email signature, which also fills it in every first email still missing it."}},"type":"object","required":["index","label","kind","request_id","target"],"title":"DraftGapResponse","description":"Something only a member can say, marked in a draft where it goes."},"EditionBody":{"properties":{"brand_name":{"type":"string","title":"Brand Name","description":"The brand's name at issue."},"ai":{"$ref":"#/components/schemas/Standing","description":"Where the brand stood in AI answers."},"google":{"$ref":"#/components/schemas/Standing","description":"Where the brand stood in Google search."},"moved":{"$ref":"#/components/schemas/Moved","description":"What moved over the period."},"focus":{"$ref":"#/components/schemas/EditionFocus","description":"The brand's focus at issue."},"work_completed":{"$ref":"#/components/schemas/WorkCompleted","description":"Work delivered over the period."},"new_pages":{"$ref":"#/components/schemas/NewPages","description":"Your pages cited for the first time over the period."},"competitors":{"$ref":"#/components/schemas/Competitors","description":"The tracked brands by score."},"next":{"$ref":"#/components/schemas/NextUp","description":"Open work and the next report date at issue."},"products":{"anyOf":[{"$ref":"#/components/schemas/EditionProducts"},{"type":"null"}],"description":"Product figures and alerts; ecommerce brands only."},"goal":{"anyOf":[{"$ref":"#/components/schemas/EditionGoal"},{"type":"null"}],"description":"The goal as it stood; quarterly editions only."},"weeks":{"items":{"$ref":"#/components/schemas/EditionWeek"},"type":"array","title":"Weeks","description":"The weekly editions a quarterly edition covers."},"made_with_heralded":{"type":"boolean","title":"Made With Heralded","description":"False for a brand a manager organization manages."}},"type":"object","required":["brand_name","ai","google","moved","focus","work_completed","new_pages","competitors","next","products","goal","weeks","made_with_heralded"],"title":"EditionBody","description":"An edition as it issued. Nothing rewrites it."},"EditionFigure":{"properties":{"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value","description":"Whole points for the score, else a whole percent."},"low":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Low","description":"Lower bound of the value's range; null when unbounded."},"high":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"High","description":"Upper bound of the value's range; null when unbounded."},"state":{"type":"string","title":"State","description":"Whether the figure was measured when it issued.","x-extensible-enum":["measured","too_few_answers","calibrating","first_report","not_comparable","not_measured","pending","not_scored"]},"change":{"type":"string","enum":["up","down","steady","calibrating","first_report","not_comparable"],"title":"Change","description":"The paired test's verdict on the move."},"delta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta","description":"The move in points; null without a comparison."}},"type":"object","required":["value","low","high","state","change","delta"],"title":"EditionFigure"},"EditionFocus":{"properties":{"state":{"type":"string","enum":["ready","missing","not_set"],"title":"State","description":"ready, or not_set when nothing was starred."},"topics":{"items":{"$ref":"#/components/schemas/FocusLine"},"type":"array","title":"Topics","description":"Starred topics."},"competitors":{"items":{"$ref":"#/components/schemas/FocusLine"},"type":"array","title":"Competitors","description":"Starred competitors."},"markets":{"items":{"$ref":"#/components/schemas/FocusLine"},"type":"array","title":"Markets","description":"Starred markets."}},"type":"object","required":["state","topics","competitors","markets"],"title":"EditionFocus","description":"The brand's stars when the report issued, each with its figures then."},"EditionGoal":{"properties":{"state":{"type":"string","enum":["ready","missing","not_set"],"title":"State","description":"ready, or not_set when the brand had no goal."},"revision":{"anyOf":[{"$ref":"#/components/schemas/Goal"},{"type":"null"}],"description":"The revision current at issue; null without a goal."}},"type":"object","required":["state","revision"],"title":"EditionGoal","description":"The goal's revision as it stood when the report issued, with its\nfigures then. Figures never compare across two revisions."},"EditionProductAlert":{"properties":{"kind":{"type":"string","enum":["price_shown_changed","product_dropped","product_replaced"],"title":"Kind","description":"price_shown_changed, product_dropped or product_replaced."},"product_id":{"type":"string","format":"uuid","title":"Product Id","description":"The product's id."},"at":{"type":"string","format":"date-time","title":"At","description":"When the run that saw the change observed it."},"answers":{"type":"integer","title":"Answers","description":"The prompt and engine pairs it was seen on."}},"type":"object","required":["kind","product_id","at","answers"],"title":"EditionProductAlert","description":"One change in how AI shopping showed one of the brand's products."},"EditionProductEvidence":{"properties":{"state":{"type":"string","enum":["complete","partial","unavailable"],"title":"State","description":"complete where the catalogue and Google Shopping were read in full, partial where one was read in part, unavailable where neither was read."}},"type":"object","required":["state"],"title":"EditionProductEvidence"},"EditionProducts":{"properties":{"shopping_meaning_version":{"type":"integer","title":"Shopping Meaning Version","description":"1 counts covered topics; 2 counts all answers with organic cards. Absent in issued editions with meaning 1.","default":1},"state":{"type":"string","enum":["ready","missing","not_set"],"title":"State","description":"ready, or missing where no product card was read."},"evidence":{"anyOf":[{"$ref":"#/components/schemas/EditionProductEvidence"},{"type":"null"}],"description":"How much of the shop's catalogue and Google Shopping the report read; null on a report that waited for neither."},"answers_with_cards":{"anyOf":[{"$ref":"#/components/schemas/EditionShare"},{"type":"null"}],"description":"Answers showing product cards, of those whose cards were read."},"in_product_cards":{"anyOf":[{"$ref":"#/components/schemas/EditionShare"},{"type":"null"}],"description":"Answers showing one of your products, of those showing organic product cards. Editions with shopping_meaning_version 1 restrict this to covered topics."},"seller_own":{"anyOf":[{"$ref":"#/components/schemas/EditionShare"},{"type":"null"}],"description":"Appearances of your products whose seller shown is your shop."},"price_matches":{"anyOf":[{"$ref":"#/components/schemas/EditionShare"},{"type":"null"}],"description":"Appearances sold by your shop whose price shown matches your shop's."},"alerts":{"items":{"$ref":"#/components/schemas/EditionProductAlert"},"type":"array","title":"Alerts","description":"Most-seen first."}},"type":"object","required":["shopping_meaning_version","state","evidence","answers_with_cards","in_product_cards","seller_own","price_matches","alerts"],"title":"EditionProducts","description":"An ecommerce brand's product figures and alerts when the report issued.\nAbsent from a B2B brand's edition."},"EditionRecipient":{"properties":{"account_id":{"type":"string","format":"uuid","title":"Account Id","description":"The person's account."},"name":{"type":"string","title":"Name","description":"The person's name, or their address where they set none."},"sent_at":{"type":"string","format":"date-time","title":"Sent At","description":"When the report was last sent to them."}},"type":"object","required":["account_id","name","sent_at"],"title":"EditionRecipient"},"EditionRecipients":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"recipients":{"items":{"$ref":"#/components/schemas/EditionRecipient"},"type":"array","title":"Recipients","description":"Newest send first."},"total":{"type":"integer","title":"Total","description":"People the report was sent to."},"limit":{"type":"integer","title":"Limit","description":"The page size asked for."}},"type":"object","required":["meta","next_cursor","recipients","total","limit"],"title":"EditionRecipients","examples":[{"recipients":[],"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"total":0}]},"EditionShare":{"properties":{"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value","description":"Whole percent of the answers it is read over."},"low":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Low","description":"Lower bound of the value's range."},"high":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"High","description":"Upper bound of the value's range."},"answers":{"type":"integer","title":"Answers","description":"The answers it was read from."}},"type":"object","required":["value","low","high","answers"],"title":"EditionShare","description":"A share of answers as the report measured it, with its range."},"EditionWeek":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The weekly edition's id."},"period_end":{"type":"string","format":"date-time","title":"Period End","description":"When that weekly report completed."}},"type":"object","required":["id","period_end"],"title":"EditionWeek"},"EndingChoiceResponse":{"properties":{"key":{"type":"string","title":"Key","description":"The ending: no_reply, declined, stopped, no_longer_waiting, or skip, which lets the follow-up due after a missed date go unsent."},"label":{"type":"string","title":"Label","description":"The words on the control."},"verb":{"type":"string","title":"Verb","description":"What it sends: the dismiss or unblock verb, close, which closes the task's emails with `key` as the reason, or skip, which skips the follow-up due and waits again. The verbs grow with the kinds of work: offer an unknown one nowhere.","x-extensible-enum":["dismiss","unblock","close","skip"]},"confirm":{"anyOf":[{"$ref":"#/components/schemas/EndingConfirmResponse"},{"type":"null"}],"description":"The confirmation it asks for first; null when none."}},"type":"object","required":["key","label","verb","confirm"],"title":"EndingChoiceResponse","description":"One way the member may end the task, or the wait it stands in."},"EndingConfirmResponse":{"properties":{"question":{"type":"string","title":"Question","description":"What the confirmation asks before the ending goes."},"confirm_label":{"type":"string","title":"Confirm Label","description":"The words on the button that confirms it."}},"type":"object","required":["question","confirm_label"],"title":"EndingConfirmResponse"},"EndingResponse":{"properties":{"key":{"type":"string","title":"Key","description":"no_reply, no_reply_recorded, declined, opted_out, stopped, not_now, too_much_work, not_relevant or already_done."},"label":{"type":"string","title":"Label","description":"The ending in words, such as No reply or Not relevant."},"at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"At","description":"When it ended."}},"type":"object","required":["key","label","at"],"title":"EndingResponse","description":"How an ended task ended."},"EngineAxisRow":{"properties":{"engine_id":{"type":"string","title":"Engine Id"},"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value"},"display":{"type":"string","title":"Display"},"numerator":{"type":"number","title":"Numerator"},"denominator":{"type":"integer","title":"Denominator"},"axis":{"type":"string","title":"Axis","default":""},"change":{"anyOf":[{"$ref":"#/components/schemas/FigureChange"},{"type":"null"}],"description":"This engine's change on the axis against its baseline."},"figure":{"$ref":"#/components/schemas/MetricFigure","readOnly":true}},"type":"object","required":["engine_id","value","display","numerator","denominator","axis","change","figure"],"title":"EngineAxisRow","description":"An engine on an axis pane's By engine list; opens the engine screen.\n\nThe percentage travels with the population it is a share of, because two\nengines on the same list rarely read the same number of answers and 50%\nof two is not 50% of twenty (BR-1)."},"EngineCoverage":{"properties":{"engine_id":{"type":"string","title":"Engine Id"},"total":{"type":"integer","title":"Total"},"scored":{"type":"integer","title":"Scored"},"named":{"type":"integer","title":"Named"},"unanswered":{"type":"integer","title":"Unanswered"},"deadline":{"type":"integer","title":"Deadline"},"dropped":{"type":"boolean","title":"Dropped"},"cut":{"type":"boolean","title":"Cut"},"partial":{"type":"boolean","title":"Partial"}},"type":"object","required":["engine_id","total","scored","named","unanswered","deadline","dropped","cut","partial"],"title":"EngineCoverage","description":"Prompt × engine cells, counted once across the run's repeated answers."},"EngineFacet":{"properties":{"engine_id":{"type":"string","enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"title":"Engine Id"},"slug":{"type":"string","title":"Slug"},"label":{"type":"string","title":"Label"}},"type":"object","required":["engine_id","slug","label"],"title":"EngineFacet"},"EngineFigures":{"properties":{"mentioned":{"$ref":"#/components/schemas/Figure"},"recommended":{"$ref":"#/components/schemas/Figure"}},"type":"object","required":["mentioned","recommended"],"title":"EngineFigures"},"EnginePoint":{"properties":{"engine_id":{"type":"string","title":"Engine Id"},"state":{"type":"string","enum":["strongly_negative","negative","neutral","positive","strongly_positive","not_mentioned","mixed"],"title":"State"},"evidence":{"type":"string","title":"Evidence","default":""}},"type":"object","required":["engine_id","state","evidence"],"title":"EnginePoint"},"EnginePrompt":{"properties":{"prompt_uid":{"type":"string","format":"uuid","title":"Prompt Uid"},"text":{"type":"string","title":"Text"},"score":{"$ref":"#/components/schemas/ScoreMark"},"change":{"$ref":"#/components/schemas/PromptTrend"}},"type":"object","required":["prompt_uid","text","score","change"],"title":"EnginePrompt"},"EngineRank":{"properties":{"engine_id":{"type":"string","title":"Engine Id"},"average_rank":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Rank"},"leaderboards":{"type":"integer","title":"Leaderboards"},"best_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Rank"}},"type":"object","required":["engine_id","average_rank","leaderboards","best_rank"],"title":"EngineRank"},"EngineRanksRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"rows":{"items":{"$ref":"#/components/schemas/EngineRank"},"type":"array","title":"Rows"}},"type":"object","required":["meta","next_cursor","total","limit","offset","rows"],"title":"EngineRanksRead"},"EngineRow":{"properties":{"engine_id":{"type":"string","title":"Engine Id"},"display_name":{"type":"string","title":"Display Name"},"figures":{"$ref":"#/components/schemas/Figures"},"score":{"$ref":"#/components/schemas/ScoreMark"},"marks":{"items":{"$ref":"#/components/schemas/ScoreMark"},"type":"array","title":"Marks"},"change":{"$ref":"#/components/schemas/PromptTrend"},"answers":{"type":"integer","title":"Answers"},"prompts":{"type":"integer","title":"Prompts"}},"type":"object","required":["engine_id","display_name","figures","score","marks","change","answers","prompts"],"title":"EngineRow"},"EngineScreen":{"properties":{"answers_link":{"anyOf":[{"$ref":"#/components/schemas/AnswersLink"},{"type":"null"}]},"engine_id":{"type":"string","title":"Engine Id"},"state":{"type":"string","title":"State"},"measures":{"items":{"$ref":"#/components/schemas/Measure"},"type":"array","title":"Measures"},"trend":{"anyOf":[{"items":{"$ref":"#/components/schemas/PerceptionSeriesPoint"},"type":"array"},{"type":"null"}],"title":"Trend"},"prompt_order":{"items":{"type":"string"},"type":"array","title":"Prompt Order"}},"type":"object","required":["answers_link","engine_id","state","measures","trend","prompt_order"],"title":"EngineScreen","description":"That axis's measures for one engine, and the prompts it read (BR-5)."},"EngineVocabulary":{"properties":{"engine_id":{"type":"string","title":"Engine Id"},"display_name":{"type":"string","title":"Display Name"},"sort_order":{"type":"integer","title":"Sort Order"}},"type":"object","required":["engine_id","display_name","sort_order"],"title":"EngineVocabulary"},"EnginesPage":{"properties":{"period":{"$ref":"#/components/schemas/PeriodDescriptor"},"filters":{"$ref":"#/components/schemas/FigureFilters"},"rows":{"items":{"$ref":"#/components/schemas/EngineRow"},"type":"array","title":"Rows"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["period","filters","rows","total","limit","offset"],"title":"EnginesPage"},"EnginesRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"rows":{"items":{"$ref":"#/components/schemas/LeaderboardEngineRow"},"type":"array","title":"Rows"}},"type":"object","required":["meta","next_cursor","total","limit","offset","rows"],"title":"EnginesRead"},"EnglishTopicName":{"properties":{"source_name":{"type":"string","title":"Source Name"},"name":{"type":"string","maxLength":60,"minLength":1,"title":"Name"}},"type":"object","required":["source_name","name"],"title":"EnglishTopicName"},"Evidence":{"properties":{"observed_at":{"type":"string","format":"date-time","title":"Observed At"},"fact":{"type":"string","title":"Fact"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"measure":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Measure","description":"Stable measure whose newest observation replaces an older one."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The cited page supporting this observation."}},"type":"object","required":["observed_at","fact"],"title":"Evidence"},"Facets":{"properties":{"industries":{"items":{"$ref":"#/components/schemas/IndustryFacet"},"type":"array","title":"Industries"},"countries":{"items":{"type":"string"},"type":"array","title":"Countries"},"engines":{"items":{"$ref":"#/components/schemas/EngineFacet"},"type":"array","title":"Engines"},"origins":{"items":{"type":"string"},"type":"array","title":"Origins"}},"type":"object","required":["industries","countries","engines","origins"],"title":"Facets"},"FacetsRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"facets":{"$ref":"#/components/schemas/Facets"},"month":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Month"},"pages":{"items":{"$ref":"#/components/schemas/LeaderboardPage"},"type":"array","title":"Pages"},"score_bands":{"items":{"$ref":"#/components/schemas/ScoreBand"},"type":"array","title":"Score Bands"}},"type":"object","required":["meta","facets","month","pages","score_bands"],"title":"FacetsRead"},"FactDefinition":{"properties":{"statement":{"type":"string","maxLength":300,"minLength":1,"title":"Statement","description":"One plain sentence naming the brand, preserving subject, scope, time, units and qualifiers. Do not invent or broaden a claim."},"kind":{"type":"string","enum":["company","number","audience","offer","category","opinion"],"title":"Kind","description":"The kind of claim, or opinion when it cannot be measured."},"check":{"anyOf":[{"type":"string","maxLength":300,"minLength":1},{"type":"null"}],"title":"Check","description":"The comparison in words for a quantity, date or range, including its units, scope, time and qualifiers. Null when simple agreement suffices, and for an opinion."},"question":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Question","description":"A natural buyer question explicitly naming the brand, in the Default segment's language. Null only for an opinion."},"suggestion":{"anyOf":[{"type":"string","maxLength":300,"minLength":1},{"type":"null"}],"title":"Suggestion","description":"For an opinion, suggest tracking Recommended or a concrete reason the brand is best. Null for a measurable fact."}},"type":"object","required":["statement","kind","check","question","suggestion"],"title":"FactDefinition"},"FactOrigins":{"properties":{"probe":{"$ref":"#/components/schemas/Verdicts","description":"Answers to the fact's own question, asked once per engine each week."},"prompt":{"$ref":"#/components/schemas/Verdicts","description":"Answers to tracked prompts that name the brand."}},"type":"object","required":["probe","prompt"],"title":"FactOrigins","description":"A fact's verdict counts by where the answers came from."},"FactSource":{"properties":{"piece_id":{"type":"string","format":"uuid","title":"Piece Id"},"title":{"type":"string","title":"Title"}},"type":"object","required":["piece_id","title"],"title":"FactSource","description":"The Content Studio piece a member saved a fact from."},"FactSummary":{"properties":{"mostly_right":{"type":"integer","title":"Mostly Right","description":"Facts with strictly more agreeing than other addressing answers. A profile statement measured part by part counts as its parts."},"measured":{"type":"integer","title":"Measured","description":"Facts, profile claims and, where measured, their parts, addressed by at least three answers."},"insufficient_keys":{"items":{"type":"string"},"type":"array","title":"Insufficient Keys","description":"Fact, claim or part keys with fewer than three agrees, partly or contradicts answers; doesnt_say is excluded."}},"type":"object","required":["mostly_right","measured","insufficient_keys"],"title":"FactSummary"},"FeaturedRead":{"properties":{"state":{"type":"string","title":"State","description":"The selected featured request's state, or empty."},"image":{"anyOf":[{"$ref":"#/components/schemas/ImageFile"},{"type":"null"}],"description":"The selected featured image, if set."},"generations_left":{"type":"integer","title":"Generations Left","description":"Remaining out of ten, less this piece's successful and AI-refused generations."},"earlier_results":{"items":{"$ref":"#/components/schemas/ImageResult"},"type":"array","title":"Earlier Results","description":"This piece's generation requests, newest first, including failures."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"The latest generation description, else the suggested subject."},"style":{"type":"string","enum":["photo","illustration","three_d","isometric","line_art","abstract"],"title":"Style","description":"The latest generation's style preset.","default":"photo"},"suggestion_state":{"type":"string","title":"Suggestion State","description":"The one-time description suggestion's state.","default":"empty"},"shows_real_person":{"type":"boolean","title":"Shows Real Person","description":"Whether removing the selected upload withdraws consent and deletes its file.","default":false},"generation_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Generation State","description":"A generation still running or waiting after any image selection."},"suggested_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Suggested Description","description":"The first suggested subject, kept unchanged for this piece."},"failure_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failure Code","description":"The selected request's machine-readable failure reason."},"failure_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failure Reason","description":"The selected request's refusal or failure explanation."}},"type":"object","required":["state","image","generations_left","earlier_results","description","style","suggestion_state","shows_real_person","generation_state","suggested_description","failure_code","failure_reason"],"title":"FeaturedRead"},"Figure":{"properties":{"basis":{"type":"string","enum":["ai","ai_and_web","search"],"title":"Basis","description":"Evidence used by this figure.","default":"ai"},"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value"},"low":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Low"},"high":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"High"},"numerator":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Numerator"},"denominator":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Denominator"},"answers":{"type":"integer","title":"Answers"},"state":{"type":"string","title":"State","x-extensible-enum":["measured","too_few_answers","calibrating","first_report","not_comparable","not_measured","pending","not_scored"]},"change":{"anyOf":[{"$ref":"#/components/schemas/FigureChange"},{"type":"null"}]},"trend":{"items":{"$ref":"#/components/schemas/FigurePoint"},"type":"array","title":"Trend"}},"type":"object","required":["basis","value","low","high","numerator","denominator","answers","state","change","trend"],"title":"Figure"},"FigureChange":{"properties":{"state":{"type":"string","enum":["up","down","steady","calibrating","first_report","not_comparable"],"title":"State","description":"The served comparison state, distinct from whether the figure is measured.","default":"calibrating"},"delta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta","description":"The move in points: the shown value minus the baseline's, both as the trend draws them, or both over `compared_engines` where it names engines. Null when the baseline has no value."},"low":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Low","description":"The lower end of the paired test's 95% range for the move, in points."},"high":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"High","description":"The upper end of the paired test's 95% range for the move, in points."},"real":{"type":"boolean","title":"Real","description":"Whether the paired test over the prompt × engine cells both reads measured says the figure moved. The state is up or down only when this is true and the move has the sign of `delta`; otherwise it is steady and carries the signed `delta`."},"direction":{"type":"string","enum":["up","down","steady"],"title":"Direction"},"baseline":{"$ref":"#/components/schemas/ComparisonPeriod"},"cells_unpaired":{"type":"integer","title":"Cells Unpaired"},"compared_engines":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Compared Engines","description":"The engines `delta` was sized on, when the baseline report asked other engines than the current period. The value and the trend still include every engine asked. Null when the size is the move the trend draws."}},"type":"object","required":["state","delta","low","high","real","direction","baseline","cells_unpaired","compared_engines"],"title":"FigureChange"},"FigureFilters":{"properties":{"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market","description":"Country ISO code, europe for pooled Europe, or global for no country. Omit for all."},"audience":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","const":"all_buyers"},{"type":"null"}],"title":"Audience","description":"Audience UUID, or all_buyers for topics for all buyers. Omit for all."},"engine":{"anyOf":[{"type":"string","enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"]},{"type":"null"}],"title":"Engine","description":"Answering AI engine."},"type":{"anyOf":[{"type":"string","enum":["organic","brand_specific","competitor_comparison"]},{"type":"null"}],"title":"Type","description":"Question type."},"intent":{"anyOf":[{"type":"string","enum":["educational","problem","comparison","transactional"]},{"type":"null"}],"title":"Intent","description":"Question intent."},"topic":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Topic","description":"Tracked topic UUID."},"prompt":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Prompt","description":"Question id from list_prompts."}},"type":"object","required":["market","audience","engine","type","intent","topic","prompt"],"title":"FigureFilters"},"FigurePoint":{"properties":{"scan_id":{"type":"string","format":"uuid","title":"Scan Id"},"at":{"type":"string","format":"date-time","title":"At"},"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value"},"low":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Low"},"high":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"High"},"answers":{"type":"integer","title":"Answers"},"state":{"type":"string","title":"State","x-extensible-enum":["measured","too_few_answers","calibrating","first_report","not_comparable","not_measured","pending","not_scored"]},"key":{"$ref":"#/components/schemas/ComparabilityKey"},"breaks":{"items":{"$ref":"#/components/schemas/KeyChange"},"type":"array","title":"Breaks"},"break":{"anyOf":[{"$ref":"#/components/schemas/TrendBreak"},{"type":"null"}],"readOnly":true}},"type":"object","required":["scan_id","at","value","low","high","answers","state","key","breaks","break"],"title":"FigurePoint"},"Figures":{"properties":{"heralded_score":{"$ref":"#/components/schemas/Figure"},"mentioned":{"$ref":"#/components/schemas/Figure"},"recommended":{"$ref":"#/components/schemas/Figure"},"understood":{"$ref":"#/components/schemas/Figure"},"praised":{"$ref":"#/components/schemas/Figure"}},"type":"object","required":["heralded_score","mentioned","recommended","understood","praised"],"title":"Figures"},"FileStatus":{"properties":{"state":{"type":"string","enum":["none","pending","ready","failed"],"title":"State","description":"Whether the latest file is absent, processing, applied or failed.","default":"none"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"The failed file's problem or operation code; otherwise null."}},"type":"object","required":["state","error"],"title":"FileStatus"},"FirstCitation":{"properties":{"engine_id":{"type":"string","title":"Engine Id","description":"Engine that cited the published page."},"display_name":{"type":"string","title":"Display Name","description":"Current engine name from the engine registry."},"prompt":{"type":"string","title":"Prompt","description":"Prompt wording in the citing answer."},"prompt_uid":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Prompt Uid","description":"Stable prompt id; null on older evidence without one."},"answer_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Answer Id","description":"Answer to open; null when no answer id can be recovered."},"cited_at":{"type":"string","format":"date-time","title":"Cited At","description":"When the citing answer was observed, after publication."},"scan_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Scan Id","description":"Read that observed this citation; null when not recorded."},"mark_id":{"type":"string","title":"Mark Id","description":"Engine id used to choose its visual mark.","readOnly":true}},"type":"object","required":["engine_id","display_name","prompt","prompt_uid","answer_id","cited_at","scan_id","mark_id"],"title":"FirstCitation"},"FirstCitedPage":{"properties":{"url":{"type":"string","title":"Url","description":"The page's address."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The page's title; null where it has none."}},"type":"object","required":["url","title"],"title":"FirstCitedPage"},"FirstPlace":{"properties":{"industry":{"type":"string","title":"Industry"},"market":{"type":"string","title":"Market"},"path":{"type":"string","title":"Path"}},"type":"object","required":["industry","market","path"],"title":"FirstPlace"},"Focus":{"properties":{"topics":{"items":{"$ref":"#/components/schemas/FocusItem"},"type":"array","title":"Topics","description":"Starred topics, oldest star first."},"competitors":{"items":{"$ref":"#/components/schemas/FocusItem"},"type":"array","title":"Competitors","description":"Starred competitors, oldest star first."},"markets":{"items":{"$ref":"#/components/schemas/FocusItem"},"type":"array","title":"Markets","description":"Starred markets, oldest star first."},"limit":{"type":"integer","title":"Limit","description":"The most stars of each kind.","default":3}},"type":"object","required":["topics","competitors","markets","limit"],"title":"Focus"},"FocusCard":{"properties":{"focus":{"$ref":"#/components/schemas/FocusItem","description":"The star this card measures."},"figures":{"items":{"$ref":"#/components/schemas/FocusFigure"},"type":"array","title":"Figures","description":"Two served figures, with measurement states and ranges."}},"type":"object","required":["focus","figures"],"title":"FocusCard"},"FocusCards":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"items":{"items":{"$ref":"#/components/schemas/FocusCard"},"type":"array","title":"Items","description":"One card per starred topic, competitor and market, at most nine."}},"type":"object","required":["meta","items"],"title":"FocusCards"},"FocusFigure":{"properties":{"key":{"type":"string","enum":["recommended","mentioned","your_score","competitor_score"],"title":"Key","description":"The figure's metric or side of the competitor comparison."},"figure":{"$ref":"#/components/schemas/Figure","description":"The served value, range, state and comparison."}},"type":"object","required":["key","figure"],"title":"FocusFigure"},"FocusItem":{"properties":{"kind":{"type":"string","enum":["topic","competitor","market"],"title":"Kind","description":"topic, competitor or market."},"id":{"type":"string","title":"Id","description":"The tracked topic id, competitor key or market profile id."},"name":{"type":"string","title":"Name","description":"The topic's, competitor's or market's name."},"tracked":{"type":"boolean","title":"Tracked","description":"False once the tracked topic is archived, its market is retired, or the competitor is no longer tracked; the star stays until removed."},"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market","description":"The topic's or focused market's code."},"audience_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Audience Id","description":"Audience UUID; null for All buyers."}},"type":"object","required":["kind","id","name","tracked","market","audience_id"],"title":"FocusItem"},"FocusLine":{"properties":{"kind":{"type":"string","enum":["topic","competitor","market"],"title":"Kind","description":"topic, competitor or market."},"id":{"type":"string","title":"Id","description":"The tracked topic id, competitor key or market profile id."},"name":{"type":"string","title":"Name","description":"The topic's, competitor's or market's name."},"tracked":{"type":"boolean","title":"Tracked","description":"False once the tracked topic is archived, its market is retired, or the competitor is no longer tracked; the star stays until removed."},"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market","description":"The topic's or focused market's code."},"audience_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Audience Id","description":"Audience UUID; null for All buyers."},"score":{"anyOf":[{"$ref":"#/components/schemas/EditionFigure"},{"type":"null"}],"description":"Your Heralded Score on a starred topic or market."},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank","description":"Your place among tracked brands on a starred topic."},"rank_of":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank Of","description":"Tracked brands scored on that topic."},"them":{"anyOf":[{"$ref":"#/components/schemas/CompetitorStanding"},{"type":"null"}],"description":"A starred competitor's row on the leaderboard; null when it has none."},"you":{"anyOf":[{"$ref":"#/components/schemas/CompetitorStanding"},{"type":"null"}],"description":"Your own row beside a starred competitor's."}},"type":"object","required":["kind","id","name","tracked","market","audience_id","score","rank","rank_of","them","you"],"title":"FocusLine","description":"One star and where the brand stood on it when the report issued."},"FocusTag":{"properties":{"kind":{"type":"string","enum":["topic","competitor","outside"],"title":"Kind","description":"A starred topic, a starred competitor, or outside your focus."},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"The topic id or competitor key; null outside your focus."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Its name; null outside your focus."}},"type":"object","required":["kind","id","name"],"title":"FocusTag","description":"The focus a piece of work serves."},"FreeSnapshotStatus":{"properties":{"available":{"type":"boolean","title":"Available","description":"Whether this address's next run of this product is free."},"resets_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Resets At","description":"When the next free run opens, or null when already available."}},"type":"object","required":["available","resets_at"],"title":"FreeSnapshotStatus"},"GainResponse":{"properties":{"band":{"anyOf":[{"type":"string","enum":["high","medium","low"]},{"type":"null"}],"title":"Band","description":"How far the work is expected to move what it aims at: high, medium or low. Null where Heralded does not estimate it, on work a member asked for."},"aims_at":{"type":"string","title":"Aims At","description":"What the work aims at."}},"type":"object","required":["band","aims_at"],"title":"GainResponse","description":"The gain a piece of work is expected to bring."},"Goal":{"properties":{"revision":{"type":"integer","title":"Revision","description":"The revision's number, from 1."},"goal":{"type":"string","title":"Goal","description":"The goal sentence."},"target":{"anyOf":[{"$ref":"#/components/schemas/GoalTarget"},{"type":"null"}],"description":"The Recommended target; null for none."},"reason":{"type":"string","enum":["goal_set","goal_changed","focus_changed","profile_changed","domain_changed"],"title":"Reason","description":"What started this revision."},"started_at":{"type":"string","format":"date-time","title":"Started At","description":"When this revision started."},"ended_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ended At","description":"When the next revision started."},"prompts":{"type":"integer","title":"Prompts","description":"The questions this revision is measured on."},"measure":{"$ref":"#/components/schemas/GoalMeasure","description":"The current revision's figures."}},"type":"object","required":["revision","goal","target","reason","started_at","ended_at","prompts","measure"],"title":"Goal"},"GoalBaseline":{"properties":{"recommended":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Recommended","description":"Recommended at the baseline."},"mentioned":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentioned","description":"Mentioned at the baseline."},"understood":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Understood","description":"Understood at the baseline."}},"type":"object","required":["recommended","mentioned","understood"],"title":"GoalBaseline","description":"Each figure at the baseline report, over the prompts and engines both\nreports measured. The current value where the baseline is the newest\nreport; null where the figure is not measured or a market changed setup."},"GoalMeasure":{"properties":{"progress":{"type":"string","enum":["measured","first_report","not_comparable"],"title":"Progress","description":"measured when a report since the revision's start is compared with its baseline, and each figure's change says whether the move is real; first_report before the first goal has a second report; not_comparable when the revision started after the newest report, or a market it is measured on changed setup since."},"baseline_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Baseline At","description":"When the baseline report completed."},"measured_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Measured At","description":"When the newest report completed."},"recommended":{"$ref":"#/components/schemas/Figure","description":"Recommended on the goal's questions; its change is from the baseline report and is present only when progress is measured."},"mentioned":{"$ref":"#/components/schemas/Figure","description":"Mentioned on the goal's questions, likewise."},"understood":{"$ref":"#/components/schemas/Figure","description":"Understood on the goal's questions, likewise."},"baseline":{"$ref":"#/components/schemas/GoalBaseline","description":"Each figure at the baseline report."}},"type":"object","required":["progress","baseline_at","measured_at","recommended","mentioned","understood","baseline"],"title":"GoalMeasure"},"GoalRevisionRead":{"properties":{"revision":{"type":"integer","title":"Revision","description":"The revision's number, from 1."},"goal":{"type":"string","title":"Goal","description":"The goal sentence."},"target":{"anyOf":[{"$ref":"#/components/schemas/GoalTarget"},{"type":"null"}],"description":"The Recommended target; null for none."},"reason":{"type":"string","enum":["goal_set","goal_changed","focus_changed","profile_changed","domain_changed"],"title":"Reason","description":"What started this revision."},"started_at":{"type":"string","format":"date-time","title":"Started At","description":"When this revision started."},"ended_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ended At","description":"When the next revision started."},"prompts":{"type":"integer","title":"Prompts","description":"The questions this revision is measured on."}},"type":"object","required":["revision","goal","target","reason","started_at","ended_at","prompts"],"title":"GoalRevisionRead"},"GoalTarget":{"properties":{"value":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Value","description":"Recommended, in percent of answers."},"date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date","description":"When it is aimed for; null for none."}},"type":"object","required":["value","date"],"title":"GoalTarget"},"GroundsResponse":{"properties":{"kind":{"type":"string","enum":["your_data","category_data","best_practice","you_asked"],"title":"Kind","description":"your_data: diagnosed from the brand's own reads; category_data: what is cited and ranked for rivals and the category; best_practice: known to work, with the guidance it rests on; you_asked: a member asked for it."},"cause":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cause","description":"The leading observation. Null on work a member asked for with no finding or evidence behind it."},"observed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Observed At","description":"The observation stated by the cause, when its date is known."},"evidence":{"items":{"$ref":"#/components/schemas/Evidence"},"type":"array","title":"Evidence","description":"The dated observations the work rests on, besides the one the cause states."},"targets":{"items":{"$ref":"#/components/schemas/Target"},"type":"array","title":"Targets","description":"The prompt or keyword results this work targets."},"why":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Why","description":"Why this evidence calls for this work."},"guidance":{"items":{"$ref":"#/components/schemas/Guidance"},"type":"array","title":"Guidance","description":"The publisher guidance a best-practice action rests on, with the date Heralded last checked it. Empty on other grounds."}},"type":"object","required":["kind","cause","evidence","guidance"],"title":"GroundsResponse","description":"What a piece of work rests on (#6065)."},"Guidance":{"properties":{"publisher":{"type":"string","title":"Publisher"},"title":{"type":"string","title":"Title"},"url":{"type":"string","title":"Url"},"checked_on":{"type":"string","format":"date","title":"Checked On","description":"When Heralded last read the guidance."}},"type":"object","required":["publisher","title","url","checked_on"],"title":"Guidance","description":"The publisher guidance a best-practice play rests on."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HallOfFame":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"rows":{"items":{"$ref":"#/components/schemas/MedalRow"},"type":"array","title":"Rows"}},"type":"object","required":["meta","next_cursor","total","limit","offset","rows"],"title":"HallOfFame","examples":[{"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"rows":[],"total":0}]},"HealthWeek":{"properties":{"at":{"type":"string","format":"date-time","title":"At","description":"When the week's latest report completed."},"answers":{"type":"integer","title":"Answers","description":"Answers read for brands, each counted once."},"naming":{"type":"integer","title":"Naming","description":"Of those, answers naming any company."},"rate":{"type":"number","title":"Rate"}},"type":"object","required":["at","answers","naming","rate"],"title":"HealthWeek"},"HeraldGreeting":{"properties":{"greeting":{"type":"string","title":"Greeting","description":"A template greeting, served without a model call."},"decisions_waiting":{"type":"integer","title":"Decisions Waiting","description":"Your-input work assigned to you or unassigned. Read-only callers see the brand's whole set."},"new_results":{"type":"integer","title":"New Results","description":"Delivered actions whose latest delivery, citation or measured outcome is newer than seen_at. Null seen_at counts all results."},"seen_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Seen At","description":"The caller's last recorded visit to Home, or null before their first visit."},"address":{"$ref":"#/components/schemas/SubjectAddress","description":"The page address to attach to a message as data-context."},"suggestions":{"items":{"type":"string"},"type":"array","title":"Suggestions","description":"Templated questions about this page and the served counts. No work starts until confirmed."}},"type":"object","required":["greeting","decisions_waiting","new_results","seen_at","address","suggestions"],"title":"HeraldGreeting"},"HeraldedScore":{"properties":{"value":{"type":"integer","title":"Value"},"low":{"type":"integer","title":"Low"},"high":{"type":"integer","title":"High"},"answers":{"type":"integer","title":"Answers"},"change":{"anyOf":[{"$ref":"#/components/schemas/PairedChange"},{"type":"null"}]},"band":{"type":"string","title":"Band","readOnly":true},"bands":{"items":{"$ref":"#/components/schemas/ScoreBand"},"type":"array","title":"Bands","readOnly":true}},"type":"object","required":["value","low","high","answers","change","band","bands"],"title":"HeraldedScore","description":"The Heralded Score in points, its 95% range, and the answers read, with\nthe band it falls in and every band in order, so a surface names and draws\nthe band from the payload."},"Highlight":{"properties":{"filters":{"$ref":"#/components/schemas/LeaderboardFilters"},"prompt_id":{"type":"string","format":"uuid","title":"Prompt Id"},"engine_id":{"type":"string","title":"Engine Id"},"quote":{"type":"string","title":"Quote"},"path":{"type":"string","title":"Path"},"title":{"type":"string","title":"Title"},"question":{"type":"string","title":"Question"}},"type":"object","required":["filters","prompt_id","engine_id","quote","path","title","question"],"title":"Highlight"},"HighlightsRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"withheld":{"items":{"type":"integer"},"type":"array","title":"Withheld","description":"Ranks present in the module whose rows are withheld."},"rows":{"items":{"$ref":"#/components/schemas/Highlight"},"type":"array","title":"Rows"},"state":{"type":"string","enum":["complete","partial","unavailable"],"title":"State"}},"type":"object","required":["meta","next_cursor","total","limit","offset","withheld","rows","state"],"title":"HighlightsRead"},"HomeToday":{"properties":{"state":{"type":"string","enum":["A","B","C","D"],"title":"State","description":"A: viewer decisions; B: team decisions; C: only Heralded running; D: idle."},"date":{"type":"string","format":"date","title":"Date","description":"Today's date in UTC."},"title":{"type":"string","title":"Title","description":"The heading for the viewer's current state."},"line":{"type":"string","title":"Line","description":"What else is in flight, or where to begin."},"viewer_decisions":{"items":{"$ref":"#/components/schemas/WorkRowResponse"},"type":"array","title":"Viewer Decisions","description":"Up to three viewer decisions."},"viewer_decision_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Viewer Decision Ids","description":"The displayed viewer decisions in review order."},"viewer_total":{"type":"integer","title":"Viewer Total","description":"Every decision currently waiting on the viewer."},"viewer_more":{"type":"integer","title":"Viewer More","description":"Viewer decisions beyond the three shown."},"team_open":{"items":{"$ref":"#/components/schemas/TodayTeamDecision"},"type":"array","title":"Team Open","description":"The two oldest team decisions."},"team_total":{"type":"integer","title":"Team Total","description":"Every open decision assigned to someone else."},"heralded_running":{"items":{"$ref":"#/components/schemas/WorkRowResponse"},"type":"array","title":"Heralded Running","description":"The first three items Heralded is running."},"running_total":{"type":"integer","title":"Running Total","description":"Every item Heralded is running, including recurring jobs."},"running_more":{"type":"integer","title":"Running More","description":"Running items beyond those shown."},"running_line":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Running Line","description":"What Heralded has in progress; null when idle."},"suggestions":{"items":{"$ref":"#/components/schemas/TodaySuggestion"},"type":"array","title":"Suggestions","description":"Suggestions in Work order, focus first."},"in_flight":{"type":"integer","title":"In Flight","description":"Viewer decisions, team decisions and running items combined."}},"type":"object","required":["state","date","title","line","viewer_decisions","viewer_decision_ids","viewer_total","viewer_more","team_open","team_total","heralded_running","running_total","running_more","running_line","suggestions","in_flight"],"title":"HomeToday"},"IconStates":{"properties":{"mentioned":{"type":"string","enum":["yes","partial","no","not_measured"],"title":"Mentioned"},"understood":{"type":"string","enum":["yes","partial","no","not_measured"],"title":"Understood"},"recommended":{"type":"string","enum":["yes","partial","no","not_measured"],"title":"Recommended"},"praised":{"type":"string","enum":["yes","partial","no","not_measured"],"title":"Praised"}},"type":"object","required":["mentioned","understood","recommended","praised"],"title":"IconStates","description":"Each axis as the icon a row draws for it."},"ImageFile":{"properties":{"asset_id":{"type":"string","title":"Asset Id","description":"The stored file's asset identifier."},"version_id":{"type":"string","title":"Version Id","description":"The selected file version; no signed URL is stored."},"origin":{"type":"string","enum":["generated","uploaded","rendered","featured"],"title":"Origin","description":"How this slot's image was made or selected."},"ai_generated":{"type":"boolean","title":"Ai Generated","description":"Whether AI generated the image."},"realistic_person":{"type":"boolean","title":"Realistic Person","description":"Whether the image needs a realistic-person AI disclosure."},"width":{"type":"integer","title":"Width","description":"Image width in pixels."},"height":{"type":"integer","title":"Height","description":"Image height in pixels."},"size_bytes":{"type":"integer","title":"Size Bytes","description":"File size in bytes."}},"type":"object","required":["asset_id","version_id","origin","ai_generated","realistic_person","width","height","size_bytes"],"title":"ImageFile"},"ImageResult":{"properties":{"id":{"type":"string","title":"Id","description":"The generation result to select in Studio."},"state":{"type":"string","title":"State","description":"Generation state: pending, running, waiting, succeeded, failed or cancelled."},"description":{"type":"string","title":"Description","description":"The description requested for this generation."},"style":{"type":"string","enum":["photo","illustration","three_d","isometric","line_art","abstract"],"title":"Style","description":"The member's featured-image style preset."},"image":{"anyOf":[{"$ref":"#/components/schemas/ImageFile"},{"type":"null"}],"description":"The generated file, once successful."},"failure_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failure Code","description":"Machine-readable failure reason, when refused or failed."},"failure_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failure Reason","description":"The provider's explanation of a refusal or failure."}},"type":"object","required":["id","state","description","style","image","failure_code","failure_reason"],"title":"ImageResult"},"ImageSlots":{"properties":{"featured":{"$ref":"#/components/schemas/FeaturedRead","description":"Optional featured image and its generation allowance and earlier results."},"social":{"$ref":"#/components/schemas/SocialRead","description":"Sharing image and branded-card style."}},"type":"object","required":["featured","social"],"title":"ImageSlots"},"IndustryFacet":{"properties":{"slug":{"type":"string","title":"Slug"},"label":{"type":"string","title":"Label"},"plural_noun":{"type":"string","title":"Plural Noun"},"default_audience":{"type":"string","title":"Default Audience"}},"type":"object","required":["slug","label","plural_noun","default_audience"],"title":"IndustryFacet"},"InsightKind":{"properties":{"play":{"type":"string","title":"Play","description":"The kind of work, a play key. Send it as `kind` to file it."},"title":{"type":"string","title":"Title","description":"The work as it would be filed."},"credits":{"type":"integer","title":"Credits","description":"Content credits starting the work spends; 0 when free."}},"type":"object","required":["play","title","credits"],"title":"InsightKind"},"InsightWork":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Open it with get_action or /v1/actions/{id}."},"state":{"type":"string","title":"State","description":"The action's state."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"The customer-facing stage from the work projection; null when not loaded."}},"type":"object","required":["id","state","status"],"title":"InsightWork"},"IntentAxisRow":{"properties":{"intent":{"type":"string","title":"Intent"},"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value"},"display":{"type":"string","title":"Display"},"prompts":{"type":"integer","title":"Prompts"},"numerator":{"type":"number","title":"Numerator"},"denominator":{"type":"integer","title":"Denominator"},"axis":{"type":"string","title":"Axis","default":""},"figure":{"$ref":"#/components/schemas/MetricFigure","readOnly":true}},"type":"object","required":["intent","value","display","prompts","numerator","denominator","axis","figure"],"title":"IntentAxisRow","description":"An intent on an axis pane's By intent list; opens the intent screen."},"IntentScreen":{"properties":{"intent":{"type":"string","title":"Intent"},"prompts":{"type":"integer","title":"Prompts"},"prompts_total":{"type":"integer","title":"Prompts Total","description":"All prompts matching this selection before paging."},"mentioned":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentioned"},"recommended":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Recommended"},"search_volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Volume"},"prompt_order":{"items":{"type":"string"},"type":"array","title":"Prompt Order"}},"type":"object","required":["intent","prompts","prompts_total","mentioned","recommended","search_volume","prompt_order"],"title":"IntentScreen","description":"The prompts of one intent, with the two axes that slice by it."},"IssueType":{"type":"string","enum":["modify_content","create_content","add_keyword","pitch_to_source","request_correction","close_competitor_gap","technical_fix","setup"],"title":"IssueType"},"JobResponse":{"properties":{"kind":{"type":"string","title":"Kind"},"stages":{"items":{"$ref":"#/components/schemas/JobStageResponse"},"type":"array","title":"Stages"},"current":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current"},"stopped_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stopped At"},"failure":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failure","description":"Why the piece failed; null unless it did."},"next_step":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Step"},"control":{"type":"string","enum":["dispatch","act","take"],"title":"Control"},"runs_steps":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Runs Steps"},"step":{"anyOf":[{"$ref":"#/components/schemas/JobStepResponse"},{"type":"null"}]},"endings":{"items":{"$ref":"#/components/schemas/EndingChoiceResponse"},"type":"array","title":"Endings","description":"The ways you may end the task in its current state, an ending that answers its wait first; empty where none is offered."}},"type":"object","required":["kind","stages","current","stopped_at","failure","next_step","control","runs_steps","step","endings"],"title":"JobResponse","description":"What this row's task is as a job (#2429): every stage, where it stands,\nwhat happens next and what the button does. Composed per kind by\n`app.actions.jobs.describe_job`; no surface keeps a second table."},"JobStageResponse":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"line":{"type":"string","title":"Line"},"doer":{"type":"string","enum":["heralded","member","watch"],"title":"Doer"},"done_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Done At"},"status":{"type":"string","enum":["done","now","ahead","ended"],"title":"Status","description":"Where the stage stands: done, now, ahead, or ended, the stage an ended task had reached when it ended.","default":"ahead"},"lane":{"type":"string","enum":["main","article"],"title":"Lane","description":"Which run of the steps the stage sits in: main, or article for the article an outreach agreement needs, which runs beside the emails.","default":"main"}},"type":"object","required":["key","label","line","doer","done_at","status","lane"],"title":"JobStageResponse"},"JobStepResponse":{"properties":{"label":{"type":"string","title":"Label"},"hold_at_gate":{"type":"boolean","title":"Hold At Gate"}},"type":"object","required":["label","hold_at_gate"],"title":"JobStepResponse","description":"One stage the member may run alone where the area would run the\nwhole job: `hold_at_gate` on the dispatch request stops it at the\napproval gate (#2429)."},"JsonValue":{},"KeyChange":{"properties":{"part":{"type":"string","title":"Part","x-extensible-enum":["engines","language","market","score_version","answer_pack_version","understood_measure","sells_to","shopping_pack_version"]},"added":{"items":{"type":"string"},"type":"array","title":"Added","default":[]},"removed":{"items":{"type":"string"},"type":"array","title":"Removed","default":[]},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value"}},"type":"object","required":["part","added","removed","value"],"title":"KeyChange","description":"One part of the instrument that changed between two reads."},"KeywordCountry":{"properties":{"country":{"type":"string","title":"Country"},"searches_mo":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Searches Mo"},"volume_partial":{"type":"boolean","title":"Volume Partial"},"best_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Rank"},"last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Checked At"},"keywords":{"items":{"$ref":"#/components/schemas/CountryKeyword"},"type":"array","title":"Keywords"}},"type":"object","required":["country","searches_mo","volume_partial","best_rank","last_checked_at","keywords"],"title":"KeywordCountry"},"KeywordCoverage":{"properties":{"keyword_research":{"type":"string","enum":["available","unavailable","unknown"],"title":"Keyword Research","description":"Availability of keyword discovery: Google Keyword Planner's related searches for the market."},"search_volume":{"type":"string","enum":["available","unavailable","unknown"],"title":"Search Volume","description":"Availability of monthly keyword search volume."}},"type":"object","required":["keyword_research","search_volume"],"title":"KeywordCoverage"},"KeywordMarket":{"properties":{"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Requested country; null means Global."},"language":{"type":"string","title":"Language","description":"Keyword language code."}},"type":"object","required":["country","language"],"title":"KeywordMarket"},"KeywordMarketOption":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The stable identifier of this object."},"text":{"type":"string","title":"Text","description":"The tracked wording."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"The market’s ISO country code; null for Global."},"language":{"type":"string","title":"Language","description":"The content’s language code, or unknown when undetermined."},"best_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Rank","description":"The best own-page position in the latest Google top ten; null when absent or unchecked."},"last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Checked At","description":"When the latest fetched Google check completed; null before the first check."}},"type":"object","required":["id","text","country","language","best_rank","last_checked_at"],"title":"KeywordMarketOption"},"KeywordMeasurement":{"properties":{"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Requested country; null means Global."},"measured_country":{"type":"string","title":"Measured Country","description":"Country actually targeted; Global uses US."},"language":{"type":"string","title":"Language","description":"Product language code, independent of vendor aliases."},"coverage":{"$ref":"#/components/schemas/KeywordCoverage","description":"Current catalog availability, not a historical snapshot. Unknown means no catalog is available."}},"type":"object","required":["country","measured_country","language","coverage"],"title":"KeywordMeasurement"},"KeywordPrompt":{"properties":{"prompt_id":{"type":"string","format":"uuid","title":"Prompt Id"},"text":{"type":"string","title":"Text"},"engines":{"items":{"type":"string"},"type":"array","title":"Engines"}},"type":"object","required":["prompt_id","text","engines"],"title":"KeywordPrompt"},"KeywordResultRow":{"properties":{"position":{"type":"integer","title":"Position"},"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"domain":{"type":"string","title":"Domain"},"owner":{"type":"string","enum":["own","competitor","third_party"],"title":"Owner"},"click_share":{"type":"number","title":"Click Share"},"names_you":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Names You"},"recommends_you":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Recommends You"},"read_state":{"type":"string","enum":["read","unread","unreadable"],"title":"Read State"}},"type":"object","required":["position","url","title","domain","owner","click_share","names_you","recommends_you","read_state"],"title":"KeywordResultRow","description":"One of the ten results of the latest check."},"KeywordTopic":{"properties":{"market":{"type":"string","title":"Market","description":"The topic's market: country ISO code, europe or global.","default":"global"},"audience":{"type":"string","title":"Audience","description":"The topic's audience name.","default":"All buyers"},"audience_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Audience Id","description":"Audience UUID; null for All buyers."},"tracked_topic_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Tracked Topic Id","description":"Tracked-topic UUID."},"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"}},"type":"object","required":["market","audience","audience_id","tracked_topic_id","id","name"],"title":"KeywordTopic"},"LabelQuote":{"properties":{"quote":{"type":"string","title":"Quote","description":"The sentence of the answer that describes the brand so."},"engine_id":{"type":"string","title":"Engine Id","description":"The engine that gave the answer."},"prompt_uid":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Prompt Uid","description":"The tracked prompt the answer was asked under."},"answer_read_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Answer Read Id","description":"The answer to open for the whole text; null on a report that kept none."},"asked_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asked Language","description":"The language the prompt was asked in, where it froze one."},"language":{"type":"string","title":"Language","description":"The language of the quote, `unknown` where not read.","default":"unknown"}},"type":"object","required":["quote","engine_id","prompt_uid","answer_read_id","asked_language","language"],"title":"LabelQuote","description":"The newest answer's words that describe the brand with the label."},"LanguageCode":{"type":"string","enum":["en","ro","de","nl","fr","es","it","pt","pl","da","sv","no","fi","cs","hu","bg","el","tr","ja","zh"],"title":"LanguageCode"},"Leaderboard":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"filters":{"$ref":"#/components/schemas/LeaderboardFilters"},"month":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Month"},"ranked":{"type":"boolean","title":"Ranked"},"population":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Population"},"leader":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Leader"},"months":{"items":{"type":"string"},"type":"array","title":"Months"},"brands":{"$ref":"#/components/schemas/BrandsRead"},"origin_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Origin Counts"},"sources":{"$ref":"#/components/schemas/SourcesRead"},"engines":{"$ref":"#/components/schemas/EnginesRead"},"prompts":{"$ref":"#/components/schemas/PromptsRead"},"previous_month":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Previous Month"},"movers":{"$ref":"#/components/schemas/Movers"},"dropouts":{"$ref":"#/components/schemas/RankChangesRead"}},"type":"object","required":["meta","filters","month","ranked","population","leader","months","brands","origin_counts","sources","engines","prompts","previous_month","movers","dropouts"],"title":"Leaderboard"},"LeaderboardEngineRow":{"properties":{"engine_id":{"type":"string","title":"Engine Id"},"top_three":{"items":{"$ref":"#/components/schemas/BrandRow"},"type":"array","title":"Top Three"}},"type":"object","required":["engine_id","top_three"],"title":"LeaderboardEngineRow"},"LeaderboardFilters":{"properties":{"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry","description":"An industry slug from the facets."},"country":{"anyOf":[{"type":"string","pattern":"^(?:[A-Z]{2}|europe)$"},{"type":"null"}],"title":"Country","description":"The market asked from: an ISO 3166-1 alpha-2 country, or `europe` for the board pooling the seven European countries. Omit it for Global."},"month":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Month","description":"Publication month as YYYY-MM; omit for the latest."},"side":{"type":"string","enum":["all","ai","search"],"title":"Side","description":"AI and All use Heralded Scores and comparable history. Search keeps Google shares without a score or rank, and is empty where Google was not measured.","default":"all"},"origin_country":{"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$"},{"type":"null"}],"title":"Origin Country","description":"Brand origin as an ISO country code."},"order":{"type":"string","enum":["default","medals"],"title":"Order","description":"Order by scores or podium places.","default":"default"},"q":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Q","description":"Brand-name substring search."},"audience":{"anyOf":[{"type":"string","enum":["b2b","b2c","both"]},{"type":"null"}],"title":"Audience","description":"Filter brands by their audience."},"source_type":{"anyOf":[{"type":"string","enum":["industry_authority","review","regulatory","media","educational","community","consulting","social","vendor","directory","unclassified"]},{"type":"string","const":"brand_site"},{"type":"null"}],"title":"Source Type","description":"Filter by source category."},"include_brand_sites":{"type":"boolean","title":"Include Brand Sites","description":"Include brand sites in the source ranking and its total.","default":false}},"type":"object","required":["industry","country","month","side","origin_country","order","q","audience","source_type","include_brand_sites"],"title":"LeaderboardFilters"},"LeaderboardLeader":{"properties":{"brand_id":{"type":"string","format":"uuid","title":"Brand Id"},"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"}},"type":"object","required":["brand_id","name","slug","domain"],"title":"LeaderboardLeader"},"LeaderboardPage":{"properties":{"filters":{"$ref":"#/components/schemas/LeaderboardFilters"},"path":{"type":"string","title":"Path"},"ranked":{"type":"boolean","title":"Ranked"},"title":{"type":"string","title":"Title"},"description":{"type":"string","title":"Description"},"brand_count":{"type":"integer","title":"Brand Count","description":"Brands in this leaderboard page."},"indexed":{"type":"boolean","title":"Indexed"},"canonical_parent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Parent"},"canonical":{"type":"string","title":"Canonical"},"featured_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Featured Position"},"leader":{"anyOf":[{"$ref":"#/components/schemas/LeaderboardLeader"},{"type":"null"}]}},"type":"object","required":["filters","path","ranked","title","description","brand_count","indexed","canonical_parent","canonical","featured_position","leader"],"title":"LeaderboardPage"},"LeaderboardPromptRow":{"properties":{"prompt_id":{"type":"string","format":"uuid","title":"Prompt Id"},"industry":{"type":"string","title":"Industry"},"text":{"type":"string","title":"Text"},"language":{"type":"string","title":"Language"},"winners":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Winners"}},"type":"object","required":["prompt_id","industry","text","language","winners"],"title":"LeaderboardPromptRow"},"Look":{"properties":{"logo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo"},"colors":{"additionalProperties":{"type":"string"},"type":"object","title":"Colors","default":{}},"fonts":{"items":{"$ref":"#/components/schemas/LookFont"},"type":"array","title":"Fonts","default":[]},"buttons":{"additionalProperties":{"$ref":"#/components/schemas/LookButton"},"type":"object","title":"Buttons","default":{}},"radius":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Radius"}},"type":"object","required":["logo","colors","fonts","buttons","radius"],"title":"Look"},"LookButton":{"properties":{"background":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Background"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"},"border":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Border"},"radius":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Radius"}},"type":"object","required":["background","text","border","radius"],"title":"LookButton"},"LookColors":{"properties":{"primary":{"type":"string","title":"Primary","description":"Primary colour as six-digit hex.","default":"#000000"},"accent":{"type":"string","title":"Accent","description":"Accent colour as six-digit hex.","default":"#000000"},"text":{"type":"string","title":"Text","description":"Text colour as six-digit hex.","default":"#000000"},"background":{"type":"string","title":"Background","description":"Background colour as six-digit hex.","default":"#ffffff"}},"type":"object","required":["primary","accent","text","background"],"title":"LookColors"},"LookFont":{"properties":{"family":{"type":"string","title":"Family"},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role"}},"type":"object","required":["family","role"],"title":"LookFont"},"LookFontRead":{"properties":{"family":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Family","description":"Font family, or null for the default font."},"source":{"type":"string","enum":["website","uploaded","default"],"title":"Source","description":"Whether the font comes from the website, a member upload, or the default.","default":"default"}},"type":"object","required":["family","source"],"title":"LookFontRead"},"ManagerPortfolioAccount":{"properties":{"organization_id":{"type":"string","title":"Organization Id"},"name":{"type":"string","title":"Name"},"brand_count":{"type":"integer","title":"Brand Count","description":"Brands in this account's served scope."},"is_yours":{"type":"boolean","title":"Is Yours","description":"Whether this is the manager's own organization."}},"type":"object","required":["organization_id","name","brand_count","is_yours"],"title":"ManagerPortfolioAccount"},"ManagerPortfolioBrandRow":{"properties":{"brand_id":{"type":"string","title":"Brand Id"},"domain":{"type":"string","title":"Domain"},"data_as_of":{"anyOf":[{"$ref":"#/components/schemas/DataAsOf"},{"type":"null"}]},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score"},"score_change":{"anyOf":[{"$ref":"#/components/schemas/PairedChange"},{"type":"null"}]},"axes":{"items":{"$ref":"#/components/schemas/PortfolioAxis"},"type":"array","title":"Axes","default":[]},"actions_waiting":{"type":"integer","title":"Actions Waiting","default":0},"movement_since_deep_read":{"type":"integer","title":"Movement Since Deep Read","default":0},"name":{"type":"string","title":"Name"},"managed_account":{"$ref":"#/components/schemas/PortfolioManagedAccount"},"score_band":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Score Band","description":"The band `score` falls in, so the row names it; null without a score.","readOnly":true}},"type":"object","required":["brand_id","domain","data_as_of","score","score_change","axes","actions_waiting","movement_since_deep_read","name","managed_account","score_band"],"title":"ManagerPortfolioBrandRow","description":"One brand of the manager portfolio: the organization row's numbers\nbeside the brand's name and the account that owns it."},"MarketAdValue":{"properties":{"kind":{"type":"string","const":"estimate","title":"Kind","description":"An estimate.","default":"estimate"},"usd":{"type":"number","title":"Usd","description":"Monthly ad value in USD."},"eur":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eur","description":"Monthly ad value in EUR; null without an ECB rate."},"click_rate":{"type":"number","title":"Click Rate","description":"The stored clicks per search or question priced."},"demand":{"type":"integer","title":"Demand","description":"Monthly Google searches plus estimated LLM questions."},"ai_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ai Share","description":"The share of that demand AI answers: searches opening with Google's AI summary and LLM questions; null without an AI summary share."}},"type":"object","required":["kind","usd","eur","click_rate","demand","ai_share"],"title":"MarketAdValue","description":"What Google Ads would charge for the clicks the top result gets across the\ncategory's Google searches and LLM questions."},"MarketAiSummary":{"properties":{"kind":{"type":"string","const":"measured","title":"Kind","description":"Measured Google figures.","default":"measured"},"share":{"type":"number","title":"Share","description":"The share of the top searches, weighted by volume, that open with Google's AI summary."},"checked":{"type":"integer","title":"Checked","description":"Top searches whose Google results were successfully checked."},"searches":{"type":"integer","title":"Searches","description":"Top searches selected for checking, including failed checks."}},"type":"object","required":["kind","share","checked","searches"],"title":"MarketAiSummary"},"MarketBrand":{"properties":{"name":{"type":"string","title":"Name","description":"The brand's name."},"you":{"type":"boolean","title":"You","description":"Whether this is the Snapshot's subject brand."},"share":{"type":"number","title":"Share","description":"Share of this engine's answers, from 0 to 1."},"low":{"type":"number","title":"Low","description":"Lower bound of the share's 95% range, from 0 to 1."},"high":{"type":"number","title":"High","description":"Upper bound of the share's 95% range, from 0 to 1."}},"type":"object","required":["name","you","share","low","high"],"title":"MarketBrand"},"MarketCapture":{"properties":{"kind":{"type":"string","const":"estimate","title":"Kind","description":"An estimate.","default":"estimate"},"google":{"anyOf":[{"$ref":"#/components/schemas/MarketCaptureGoogle"},{"type":"null"}],"description":"Of the Google searches; null where no checked page's results were kept."},"llms":{"anyOf":[{"$ref":"#/components/schemas/MarketCaptureLlms"},{"type":"null"}],"description":"Of the LLM questions; null without the estimate or the LLMs panel."},"ad_value":{"anyOf":[{"$ref":"#/components/schemas/MarketCaptureAdValue"},{"type":"null"}],"description":"Of the ad value; null where either of the others is."}},"type":"object","required":["kind","google","llms","ad_value"],"title":"MarketCapture","description":"What the brand holds of each figure today, as the top spot's equivalent."},"MarketCaptureAdValue":{"properties":{"usd":{"type":"number","title":"Usd","description":"Monthly ad value of what the brand holds, in USD."},"eur":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eur","description":"The same in EUR; null without an ECB rate."},"share":{"type":"number","title":"Share","description":"Its share of the market's ad value, from 0 to 1."}},"type":"object","required":["usd","eur","share"],"title":"MarketCaptureAdValue"},"MarketCaptureGoogle":{"properties":{"clicks":{"type":"integer","title":"Clicks","description":"Monthly top-spot clicks the brand holds of the searches."},"share":{"type":"number","title":"Share","description":"Their share of what the top spot would get, from 0 to 1."}},"type":"object","required":["clicks","share"],"title":"MarketCaptureGoogle"},"MarketCaptureLlms":{"properties":{"questions":{"type":"integer","title":"Questions","description":"Monthly LLM questions whose answers recommend the brand."},"share":{"type":"number","title":"Share","description":"Their share of the LLM questions, from 0 to 1."}},"type":"object","required":["questions","share"],"title":"MarketCaptureLlms"},"MarketDemand":{"properties":{"kind":{"type":"string","const":"measured","title":"Kind","description":"Measured Google figures.","default":"measured"},"state":{"type":"string","enum":["pending","unknown","low","measured"],"title":"State","description":"Measured, low demand or unknown demand."},"searches":{"type":"integer","title":"Searches","description":"Monthly category searches in the measured countries."},"ad_value_usd":{"type":"number","title":"Ad Value Usd","description":"Monthly priced search volume times CPC, in USD. Kept for the report's web section until it reads `ad_value`, then removed."},"price_per_click_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price Per Click Usd","description":"Ad value per priced search, in USD; null without priced searches."},"ad_value_eur":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ad Value Eur","description":"`ad_value_usd` in EUR at the stored ECB rate; null without a rate. Kept for the report's web section until it reads `ad_value`, then removed."},"price_per_click_eur":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price Per Click Eur","description":"Price per click in EUR; null without priced searches or an ECB rate."},"usd_per_eur":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Usd Per Eur","description":"The ECB reference rate the euros are at."},"rate_published":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rate Published","description":"The day the ECB published that rate."}},"type":"object","required":["kind","state","searches","ad_value_usd","price_per_click_usd","ad_value_eur","price_per_click_eur","usd_per_eur","rate_published"],"title":"MarketDemand","description":"Google's measured demand for the category, in the countries that answered."},"MarketEstimate":{"properties":{"kind":{"type":"string","const":"estimate","title":"Kind","description":"Estimated ChatGPT volume.","default":"estimate"},"questions":{"type":"integer","title":"Questions","description":"Estimated monthly search-like ChatGPT questions."},"ratio":{"type":"number","title":"Ratio","description":"The stored ratio of ChatGPT questions to Google searches."}},"type":"object","required":["kind","questions","ratio"],"title":"MarketEstimate","description":"ChatGPT's search-like questions a month: an estimate, never added to Google's."},"MarketFigures":{"properties":{"version":{"type":"integer","title":"Version","description":"The stored market claim's schema version."},"constants_version":{"type":"string","title":"Constants Version","description":"The constants version used for these stored figures."},"vertical":{"type":"string","title":"Vertical","description":"The category confirmed in the Snapshot brief."},"searches_kind":{"type":"string","enum":["top","tracked"],"title":"Searches Kind","description":"Top category searches, or a weekly Snapshot's tracked searches.","default":"top"},"scope":{"$ref":"#/components/schemas/MarketScope","description":"The market and countries these figures cover."},"demand":{"anyOf":[{"$ref":"#/components/schemas/MarketDemand"},{"type":"null"}],"description":"Google category demand; null without research."},"ai_summary":{"anyOf":[{"$ref":"#/components/schemas/MarketAiSummary"},{"type":"null"}],"description":"AI summary share of top searches; null without successful checks."},"chatgpt_estimate":{"anyOf":[{"$ref":"#/components/schemas/MarketEstimate"},{"type":"null"}],"description":"ChatGPT volume estimate; null when Google demand is unknown. Kept for the report's web section until it reads `llm_estimate`, then removed."},"llm_estimate":{"anyOf":[{"$ref":"#/components/schemas/MarketLlmEstimate"},{"type":"null"}],"description":"LLM questions estimate; null when Google demand is unknown."},"ad_value":{"anyOf":[{"$ref":"#/components/schemas/MarketAdValue"},{"type":"null"}],"description":"Ad value of the category's demand; null without demand or a price per click."},"capture":{"anyOf":[{"$ref":"#/components/schemas/MarketCapture"},{"type":"null"}],"description":"What the subject holds of each figure; null without demand."},"panels":{"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/MarketPanel"},{"type":"null"}]},"type":"object","title":"Panels","description":"`google_aio` names; `llms` recommends, across the LLMs; `openai` is ChatGPT alone, kept for the report's web section until it reads `llms`, then removed."},"top_searches":{"items":{"$ref":"#/components/schemas/MarketSearch"},"type":"array","title":"Top Searches","description":"Up to five top searches, highest volume first. Kept for the report's web section until it reads `searches_by_meaning`, then removed."},"searches_by_meaning":{"items":{"$ref":"#/components/schemas/MarketMeaning"},"type":"array","title":"Searches By Meaning","description":"Up to five top meanings, each grouping the searches that mean it, highest volume first."},"verdict":{"$ref":"#/components/schemas/MarketVerdict","description":"The stored structured verdict for this market."},"gap":{"anyOf":[{"$ref":"#/components/schemas/MarketGap"},{"type":"null"}],"description":"Searches the subject would appear in if named as often as its top rival; null when none is ahead or a figure is missing."}},"type":"object","required":["version","constants_version","vertical","searches_kind","scope","demand","ai_summary","chatgpt_estimate","llm_estimate","ad_value","capture","panels","top_searches","searches_by_meaning","verdict","gap"],"title":"MarketFigures","description":"The section's figures as its claim stores them."},"MarketFocusOption":{"properties":{"market":{"type":"string","title":"Market","description":"The topic's market: country ISO code, europe or global.","default":"global"},"audience":{"type":"string","title":"Audience","description":"The topic's audience name.","default":"All buyers"},"audience_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Audience Id","description":"Audience UUID; null for All buyers."},"id":{"type":"string","format":"uuid","title":"Id","description":"The market and audience's identifier for Focus."}},"type":"object","required":["market","audience","audience_id","id"],"title":"MarketFocusOption"},"MarketGap":{"properties":{"kind":{"type":"string","const":"estimate","title":"Kind","description":"An estimate.","default":"estimate"},"engine":{"type":"string","const":"google_aio","title":"Engine","description":"The engine the shares come from."},"leader":{"type":"string","title":"Leader","description":"The rival named most often in the panel."},"searches":{"type":"integer","title":"Searches","description":"Monthly searches opening with an AI summary that would name the subject."},"low":{"type":"integer","title":"Low","description":"The same at the low end of the rival's 95% range."},"high":{"type":"integer","title":"High","description":"The same at the high end of the rival's 95% range."}},"type":"object","required":["kind","engine","leader","searches","low","high"],"title":"MarketGap","description":"The searches whose Google AI summary would name the subject if it were named as\noften as its top rival: an estimate, never added to anything else."},"MarketLlmEstimate":{"properties":{"kind":{"type":"string","const":"estimate","title":"Kind","description":"Estimated LLM volume.","default":"estimate"},"questions":{"type":"integer","title":"Questions","description":"Estimated monthly search-like LLM questions."},"ratios":{"additionalProperties":{"type":"number"},"type":"object","title":"Ratios","description":"The stored ratio of each engine's questions to Google searches, by engine."}},"type":"object","required":["kind","questions","ratios"],"title":"MarketLlmEstimate","description":"The search-like questions a month buyers ask the LLMs a Snapshot reads."},"MarketMeaning":{"properties":{"kind":{"type":"string","const":"measured","title":"Kind","description":"Measured Google searches.","default":"measured"},"meaning":{"type":"string","title":"Meaning","description":"What the searches mean, in English where known."},"volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Volume","description":"Their monthly searches summed; null when unknown."},"searches":{"items":{"$ref":"#/components/schemas/MarketMeaningSearch"},"type":"array","title":"Searches","description":"The searches, most searched first."},"ai_overview":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ai Overview","description":"Whether Google showed an AI summary on any of them; null if unchecked."},"names_you":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Names You","description":"Whether any of their AI summaries names the subject; null if ungraded."},"names_rivals":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Names Rivals","description":"Rivals their AI summaries name; null if ungraded."},"your_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Your Rank","description":"The subject's best organic position over them; null if none."},"ranks_read":{"type":"boolean","title":"Ranks Read","description":"Whether any of their result pages' rankings were kept.","default":false}},"type":"object","required":["kind","meaning","volume","searches","ai_overview","names_you","names_rivals","your_rank","ranks_read"],"title":"MarketMeaning","description":"The top searches that mean one thing, as one row."},"MarketMeaningSearch":{"properties":{"text":{"type":"string","title":"Text","description":"The search as asked."},"country":{"type":"string","title":"Country","description":"The search's country code, or global for US volume."},"volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Volume","description":"Monthly search volume in this country; null when unknown."}},"type":"object","required":["text","country","volume"],"title":"MarketMeaningSearch"},"MarketPanel":{"properties":{"kind":{"type":"string","const":"measured","title":"Kind","description":"Measured answer shares.","default":"measured"},"answers":{"type":"integer","title":"Answers","description":"Answers measured for this engine's panel."},"brands":{"items":{"$ref":"#/components/schemas/MarketBrand"},"type":"array","title":"Brands","description":"The subject followed by up to three top rivals."}},"type":"object","required":["kind","answers","brands"],"title":"MarketPanel"},"MarketPosition":{"properties":{"position":{"type":"string","enum":["leads","close","behind","not_named"],"title":"Position","description":"Whether the subject leads, is close, behind or unnamed."},"rivals":{"items":{"type":"string"},"type":"array","title":"Rivals","description":"Rivals whose ranges support this position."}},"type":"object","required":["position","rivals"],"title":"MarketPosition"},"MarketScope":{"properties":{"market":{"type":"string","title":"Market","description":"A country code, `global` or `europe`."},"label":{"type":"string","title":"Label","description":"The market's name: Europe, a country, or the United States."},"floor":{"type":"boolean","title":"Floor","description":"Whether the figures are floors: Europe is its 10 measured countries."},"countries":{"items":{"type":"string"},"type":"array","title":"Countries","description":"The countries whose Planner answered."},"asked":{"type":"integer","title":"Asked","description":"How many countries were asked."}},"type":"object","required":["market","label","floor","countries","asked"],"title":"MarketScope"},"MarketSearch":{"properties":{"kind":{"type":"string","const":"measured","title":"Kind","description":"Measured Google search.","default":"measured"},"text":{"type":"string","title":"Text","description":"The search as asked."},"country":{"type":"string","title":"Country","description":"The search's country code, or global for US volume."},"volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Volume","description":"Monthly search volume in this country; null when unknown."},"gloss":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gloss","description":"English wording when available."},"ai_overview":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ai Overview","description":"Whether Google showed an AI summary; null if the check failed."},"names_you":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Names You","description":"Whether the AI summary names the subject; null if ungraded."},"names_rivals":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Names Rivals","description":"Rivals the AI summary names; null if ungraded."}},"type":"object","required":["kind","text","country","volume","gloss","ai_overview","names_you","names_rivals"],"title":"MarketSearch"},"MarketVerdict":{"properties":{"opening":{"anyOf":[{"type":"string","enum":["every","almost_every","most","about_half","some"]},{"type":"null"}],"title":"Opening","description":"AI summary share band; null when no opening applies."},"panels":{"additionalProperties":{"$ref":"#/components/schemas/MarketPosition"},"type":"object","title":"Panels","description":"The subject's position by engine."}},"type":"object","required":["opening","panels"],"title":"MarketVerdict"},"MarketsRead":{"properties":{"home_market":{"type":"string","title":"Home Market","description":"Default market for new topics."},"markets":{"items":{"type":"string"},"type":"array","title":"Markets","description":"Markets available for new topics, default first."},"vocabulary":{"additionalProperties":{"type":"string"},"type":"object","title":"Vocabulary","description":"Market codes and their display names."},"focus_options":{"items":{"$ref":"#/components/schemas/MarketFocusOption"},"type":"array","title":"Focus Options","description":"Markets you can star as Focus, with their audiences."}},"type":"object","required":["home_market","markets","vocabulary","focus_options"],"title":"MarketsRead"},"Measure":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"kind":{"type":"string","enum":["pct","five"],"title":"Kind"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"display":{"type":"string","title":"Display"},"numerator":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Numerator"},"denominator":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Denominator"},"figure":{"anyOf":[{"$ref":"#/components/schemas/MetricFigure"},{"type":"null"}],"readOnly":true}},"type":"object","required":["key","label","kind","value","display","numerator","denominator","figure"],"title":"Measure","description":"One row of a quadrant's or a pane's measure block (BR-3).\n\n`kind` says which bar draws it: `pct` is the 0-to-100 bar, `five` the\n1-to-5 segmented scale. `display` is the words beside the bar, composed\nhere so a figure reads the same on the quadrant, in the pane and on an\nengine screen."},"MedalRow":{"properties":{"brand":{"$ref":"#/components/schemas/BrandFacts"},"rank":{"type":"integer","title":"Rank"},"medals":{"$ref":"#/components/schemas/Medals"},"best_placements":{"items":{"$ref":"#/components/schemas/BestPlacement"},"type":"array","title":"Best Placements","description":"Best three ranked placements in scope, by rank, score, industry and market."},"first_places":{"items":{"$ref":"#/components/schemas/FirstPlace"},"type":"array","title":"First Places"},"europe_first_places":{"items":{"$ref":"#/components/schemas/FirstPlace"},"type":"array","title":"Europe First Places"}},"type":"object","required":["brand","rank","medals","best_placements","first_places","europe_first_places"],"title":"MedalRow"},"Medals":{"properties":{"first":{"type":"integer","title":"First","default":0},"second":{"type":"integer","title":"Second","default":0},"third":{"type":"integer","title":"Third","default":0}},"type":"object","required":["first","second","third"],"title":"Medals"},"Meta":{"properties":{"query":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object","title":"Query"},"data_as_of":{"anyOf":[{"$ref":"#/components/schemas/DataAsOf"},{"type":"null"}]},"partial":{"type":"boolean","title":"Partial","description":"The displayed response includes a partial report.","default":false},"updating":{"type":"boolean","title":"Updating","description":"A newer result is being produced or is not yet displayed.","default":false},"last_attempt_failed":{"type":"boolean","title":"Last Attempt Failed","description":"The newest attempt failed; the last good result is displayed.","default":false},"surfaces":{"additionalProperties":{"$ref":"#/components/schemas/SurfaceFreshness"},"type":"object","title":"Surfaces","description":"Freshness by Command Center surface key. Each entry describes its own displayed result, including results without a scan."}},"type":"object","required":["query","data_as_of","partial","updating","last_attempt_failed","surfaces"],"title":"Meta"},"MetricFigure":{"properties":{"pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pct"},"numerator":{"type":"number","title":"Numerator"},"denominator":{"type":"integer","title":"Denominator"},"explorer_filter":{"additionalProperties":{"type":"string"},"type":"object","title":"Explorer Filter"}},"type":"object","required":["pct","numerator","denominator","explorer_filter"],"title":"MetricFigure"},"MetricSeries":{"properties":{"metric":{"type":"string","title":"Metric"},"introduced_at_run":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Introduced At Run"},"points":{"items":{"$ref":"#/components/schemas/SeriesPoint"},"type":"array","title":"Points"}},"type":"object","required":["metric","introduced_at_run","points"],"title":"MetricSeries"},"Moved":{"properties":{"state":{"type":"string","enum":["ready","missing","not_set"],"title":"State","description":"ready, or missing on a first report."},"changes":{"items":{"$ref":"#/components/schemas/MovedRow"},"type":"array","title":"Changes","description":"Newest first."}},"type":"object","required":["state","changes"],"title":"Moved"},"MovedRow":{"properties":{"id":{"type":"string","title":"Id","description":"The change's id, as listChanges serves it.","default":""},"source":{"type":"string","title":"Source","description":"movement, insight or verification.","default":""},"kind":{"type":"string","title":"Kind","description":"The kind of change, as listChanges names it."},"at":{"type":"string","format":"date-time","title":"At","description":"When the change was observed."},"route":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Route","description":"The page the change concerns."},"pane":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pane","description":"The panel kind the change opens."},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"What that panel opens on."}},"type":"object","required":["id","source","kind","at","route","pane","key"],"title":"MovedRow"},"Movers":{"properties":{"risers":{"$ref":"#/components/schemas/RankChangesRead"},"fallers":{"$ref":"#/components/schemas/RankChangesRead"}},"type":"object","required":["risers","fallers"],"title":"Movers"},"MovingAwayLabel":{"properties":{"key":{"type":"string","title":"Key","description":"The label's stable key, the same however it is cased."},"label":{"type":"string","title":"Label","description":"The label as the profile words it."},"state":{"type":"string","enum":["measured","too_few_answers","not_measured"],"title":"State","description":"`not_measured` until a report has read an answer against the label, `too_few_answers` under three answers, which serves no share."},"answers":{"type":"integer","title":"Answers","description":"The answers naming the brand that were read against the label."},"uses":{"type":"integer","title":"Uses","description":"Of those, the answers that describe the brand with it."},"share":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Share","description":"Whole percent of answers that describe the brand with the label; null unless measured."},"low":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Low","description":"The share's 95% range, low end."},"high":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"High","description":"The share's 95% range, high end."},"trend":{"$ref":"#/components/schemas/MovingAwayTrend","description":"The change in the share against the baseline. `up` or `down` only where the paired test over the cells both periods measured calls the move real; a fall is the improvement."},"quote":{"anyOf":[{"$ref":"#/components/schemas/LabelQuote"},{"type":"null"}],"description":"The newest answer in the period that uses the label, with its words."},"pages":{"items":{"$ref":"#/components/schemas/RepeatingPage"},"type":"array","title":"Pages","description":"The pages the period's answers cited that describe the brand with the label, your own first, then the most cited."},"pages_total":{"type":"integer","title":"Pages Total","description":"All such pages before paging."}},"type":"object","required":["key","label","state","answers","uses","share","low","high","trend","quote","pages","pages_total"],"title":"MovingAwayLabel"},"MovingAwayTrend":{"properties":{"state":{"type":"string","enum":["up","down","steady","calibrating","first_report","not_comparable","none"],"title":"State","description":"`up` or `down` only where the paired test calls the move real, `none` where no answer was read against the label."},"delta":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Delta","description":"The change in whole points, signed; null where no comparison bounded one."},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"The words beside the arrow: the size of a real move, `Steady`, `Calibrating` or `First report`; null where no answer was read."}},"type":"object","required":["state","delta","label"],"title":"MovingAwayTrend","description":"The change in the share of answers that use the label: a rise is bad."},"NamedAnswerBrand":{"properties":{"name":{"type":"string","title":"Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"tracked":{"type":"boolean","title":"Tracked","default":false}},"type":"object","required":["name","domain","tracked"],"title":"NamedAnswerBrand"},"NewPages":{"properties":{"state":{"type":"string","enum":["ready","missing","not_set"],"title":"State","description":"ready, or missing on a first report."},"pages":{"items":{"$ref":"#/components/schemas/FirstCitedPage"},"type":"array","title":"Pages","description":"Your pages AI cited for the first time, in the order the report cited them."},"total":{"type":"integer","title":"Total","description":"Pages cited for the first time.","default":0}},"type":"object","required":["state","pages","total"],"title":"NewPages"},"NextEmail":{"properties":{"email":{"type":"string","title":"Email","description":"The first email, an answer to theirs, a follow-up, or the agreed article. Read an unknown value as another email of the brand's.","x-extensible-enum":["first","answer","reminder_1","reminder_2","article"]},"first":{"type":"boolean","title":"First","description":"Whether it opens its own thread: no email of the brand's has reached them yet, or it goes to another address than the last one that did."},"approved":{"type":"boolean","title":"Approved","description":"Whether a member approved it to go."},"sends":{"type":"string","enum":["heralded","member"],"title":"Sends","description":"Who sends it: Heralded from the brand's mailbox, or a member from their own mail."},"at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"At","description":"When Heralded sends it: the time its send is scheduled for, or the first working hour of the day it falls due, never before an away date they gave. Null when a member sends it or nothing has approved it."},"purpose":{"type":"string","title":"Purpose","description":"What it is for: `pitch` the first email to a source; `follow_up` a reminder in the same thread; `answer` an answer to what they asked; `hold` an answer saying the brand comes back on their terms; `decision` the brand's decision on their terms; `covering` the note the agreed article goes under; `chase` a check on a date that passed; `introduction` a first email to a new contact. Read an unknown value as another email of the brand's.","x-extensible-enum":["pitch","follow_up","answer","hold","decision","covering","chase","introduction"]},"held":{"anyOf":[{"type":"string","x-extensible-enum":["mailbox_disconnected","gap_unfilled","address_required","address_refused"]},{"type":"null"}],"title":"Held","description":"Why it can't go yet, as approving it now would be refused: the brand's mailbox that sends it is disconnected, it or a follow-up approved with it has gaps a member must fill, or there is no address to send it to. Null when nothing holds it. Read an unknown value as held."},"gaps":{"type":"integer","title":"Gaps","description":"The gaps a member still fills before it can go, in it and in the follow-ups approved with it, the brand's signature once: filling it fills every email.","default":0}},"type":"object","required":["email","first","approved","sends","at","purpose","held","gaps"],"title":"NextEmail","description":"The email of the brand's that goes next."},"NextUp":{"properties":{"needs_you":{"type":"integer","title":"Needs You","description":"Work waiting on the team."},"suggested":{"type":"integer","title":"Suggested","description":"Suggested work not yet started."},"in_progress":{"type":"integer","title":"In Progress","description":"Work Heralded is doing or waiting on."},"scheduled":{"type":"integer","title":"Scheduled","description":"Work scheduled for later."},"next_report_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Report At","description":"When the next weekly report is due; null while reports are paused."}},"type":"object","required":["needs_you","suggested","in_progress","scheduled","next_report_at"],"title":"NextUp","description":"Facts at issue: open work and the next report. No forecast."},"OfferDeliverable":{"properties":{"kind":{"type":"string","enum":["listing","review","article","link","other"],"title":"Kind","description":"The type of placement or piece offered."},"description":{"type":"string","maxLength":300,"title":"Description","description":"What this option delivers to the brand, as a noun phrase that reads inside a sentence, such as a sponsored guest article: it starts lowercase unless its first word is a proper noun the email names. Keep word counts, link counts and deadlines only in requirements, not in this description."}},"additionalProperties":false,"type":"object","required":["kind","description"],"title":"OfferDeliverable"},"OfferRequirements":{"properties":{"words":{"anyOf":[{"$ref":"#/components/schemas/OfferWords"},{"type":"null"}],"description":"Requested word band. A single stated count is normalised to a ±10% band when stored; an explicit range keeps its given limits."},"links":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Links","description":"Number of links required or allowed."},"topic":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Topic","description":"The requested subject of the piece."},"deadline":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Deadline","description":"Date they need material from the brand, as YYYY-MM-DD. Never their publication date; that belongs only on a publish commitment's by."},"words_asked":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Words Asked","description":"The stated length, such as \"900–1,100 words\".","readOnly":true}},"additionalProperties":false,"type":"object","required":["words","links","topic","deadline","words_asked"],"title":"OfferRequirements"},"OfferWords":{"properties":{"min":{"type":"integer","minimum":1.0,"title":"Min","description":"Minimum word count, inclusive."},"max":{"type":"integer","minimum":1.0,"title":"Max","description":"Maximum word count, inclusive."},"stated":{"anyOf":[{"type":"string","enum":["about","range"]},{"type":"null"}],"title":"Stated","description":"about for a single stated count, range for two explicit limits. Keep the form they stated."}},"additionalProperties":false,"type":"object","required":["min","max","stated"],"title":"OfferWords"},"Operation":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Stable identity across this operation's attempts."},"operation":{"type":"string","title":"Operation","description":"The kind of background operation."},"agent":{"type":"string","enum":["herald","writer","publicist","engineer"],"title":"Agent","description":"The agent responsible for the operation."},"status":{"type":"string","title":"Status","description":"Queued, working, needs your input, waiting on someone else, done or failed.","x-extensible-enum":["queued","working","needs_you","waiting","done","failed"]},"failure":{"anyOf":[{"type":"string","enum":["site_unreachable","provider_unavailable","timed_out","access_revoked","no_result"]},{"type":"null"}],"title":"Failure","description":"Safe failure cause on failed work only; null otherwise. Unknown causes use no_result. Never an error message or provider response."},"label":{"type":"string","title":"Label","description":"What is happening: a report's run, such as Weekly report, or the work's current step."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The action or piece this work is for; null on other work."},"feeds":{"items":{"type":"string","enum":["home.score","home.todo","home.changes","home.progress","actions.proposed","actions.work","studio.piece","content.topics","content.suggested","content.pages","visibility.score","visibility.prompts","visibility.competitors","answers","sources","perception.figures","perception.positioning","search.score","search.keywords","website.overview","website.ai_access","website.pages","website.map","website.competitors","onboarding.first_read","onboarding.topics","chat","settings.connections","reviews"]},"type":"array","title":"Feeds","description":"Sections receiving this operation's results."},"subject":{"$ref":"#/components/schemas/WorkSubject","description":"References to the work's report, item or connection."},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When the operation first started, when recorded."},"finished_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Finished At","description":"When done or failed work finished; null otherwise."},"result":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result","description":"What finished work found, in one line, where Heralded has it."},"expected_by":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expected By","description":"Expected completion, when reliable."},"progress":{"anyOf":[{"$ref":"#/components/schemas/Progress"},{"type":"null"}],"description":"Measured progress while it is being read, or null."},"destination":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Destination","description":"App destination, or null without one."},"stages":{"items":{"$ref":"#/components/schemas/Contributor"},"type":"array","title":"Stages","description":"The operation's contributors."},"current_stage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Stage","description":"The report's current stage, if working."},"primary_verb":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Verb","description":"The action's existing primary control."},"secondary_verbs":{"items":{"type":"string"},"type":"array","title":"Secondary Verbs","description":"The action's other controls."}},"type":"object","required":["id","operation","agent","status","failure","label","title","feeds","subject","started_at","finished_at","result","expected_by","progress","destination","stages","current_stage","primary_verb","secondary_verbs"],"title":"Operation"},"OptionTerms":{"properties":{"labelling":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Labelling","description":"Whole-offer and option-specific labelling combined."},"conditions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conditions","description":"Whole-offer and option-specific conditions combined."},"requirements":{"anyOf":[{"$ref":"#/components/schemas/OfferRequirements"},{"type":"null"}],"description":"The selected option's deliverable requirements."},"brand_owes":{"anyOf":[{"items":{"$ref":"#/components/schemas/OwedTerm"},"type":"array"},{"type":"null"}],"title":"Brand Owes","description":"What agreeing to the option leaves the brand to do or send, each its own item once agreed; null on options read before this was read."},"payment_due":{"anyOf":[{"type":"string","enum":["upfront","after_publication"]},{"type":"null"}],"title":"Payment Due","description":"When the option is paid: `upfront`, or `after_publication` once it is live; null where they did not say."}},"type":"object","required":["labelling","conditions","requirements","brand_owes","payment_due"],"title":"OptionTerms"},"OutreachLimitResponse":{"properties":{"routes":{"items":{"$ref":"#/components/schemas/OutreachRouteRow"},"type":"array","title":"Routes","default":[]}},"type":"object","required":["routes"],"title":"OutreachLimitResponse"},"OutreachRouteRow":{"properties":{"route":{"type":"string","title":"Route","description":"The outreach route: `pitch`, `listing`, `partnership`, `community` or `sponsored`. More may be added.","x-extensible-enum":["pitch","listing","partnership","community","sponsored"]},"label":{"type":"string","title":"Label"},"enabled":{"type":"boolean","title":"Enabled"},"limit":{"type":"integer","title":"Limit"},"choices":{"items":{"type":"integer"},"type":"array","title":"Choices"}},"type":"object","required":["route","label","enabled","limit","choices"],"title":"OutreachRouteRow","description":"One outreach route's switch and limit (#3125)."},"OwedTerm":{"properties":{"kind":{"type":"string","title":"Kind","description":"What it is, as a request of theirs would name it, such as test_account. Read an unknown value as other."},"text":{"type":"string","title":"Text","description":"A short instruction for Your side, such as Send a test account for the editor."}},"type":"object","required":["kind","text"],"title":"OwedTerm"},"OwnedContentCreate":{"properties":{"bucket":{"type":"string","const":"create","title":"Bucket","default":"create"},"title":{"type":"string","title":"Title"},"existing_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Existing Url"},"query_matches":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Query Matches"},"context":{"type":"string","title":"Context","default":""},"action":{"type":"string","title":"Action","default":""},"source":{"type":"string","enum":["competitor_evidence","keyword_demand"],"title":"Source"},"topic_volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Topic Volume"},"demand_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Demand Prompt"},"difficulty":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Difficulty"},"topic_demand":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Topic Demand"},"facets":{"items":{"$ref":"#/components/schemas/OwnedContentFacet"},"type":"array","maxItems":6,"title":"Facets"},"sub_question_coverage":{"anyOf":[{"$ref":"#/components/schemas/SubQuestionCoverage"},{"type":"null"}]}},"type":"object","required":["bucket","title","existing_url","query_matches","context","action","source","topic_volume","demand_prompt","difficulty","topic_demand","facets","sub_question_coverage"],"title":"OwnedContentCreate"},"OwnedContentFacet":{"properties":{"label":{"type":"string","title":"Label"},"covered":{"type":"boolean","title":"Covered","default":false},"source":{"type":"string","enum":["synthetic","vendor"],"title":"Source","default":"synthetic"},"basis":{"anyOf":[{"type":"string","enum":["prompt","evidence"]},{"type":"null"}],"title":"Basis","description":"The current coverage basis. Absent on historical checklists. source keeps its legacy values; synthetic includes Heralded's topic prompts and evidence."}},"type":"object","required":["label","covered","source"],"title":"OwnedContentFacet","description":"A topic prompt or evidence question, and whether the page answers it."},"OwnedContentPage":{"properties":{"bucket":{"type":"string","enum":["cited_strong","improve"],"title":"Bucket"},"url":{"type":"string","title":"Url"},"page_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Title"},"citation_count":{"type":"integer","minimum":0.0,"title":"Citation Count","description":"Citation occurrences of this page or source in the scan."},"query_matches":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Query Matches"},"weak":{"type":"boolean","title":"Weak","default":false},"context":{"type":"string","title":"Context","default":""},"topic_volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Topic Volume"},"demand_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Demand Prompt"},"difficulty":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Difficulty"},"topic_demand":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Topic Demand"},"facets":{"items":{"$ref":"#/components/schemas/OwnedContentFacet"},"type":"array","maxItems":6,"title":"Facets"},"sub_question_coverage":{"anyOf":[{"$ref":"#/components/schemas/SubQuestionCoverage"},{"type":"null"}]},"shortfall":{"anyOf":[{"$ref":"#/components/schemas/OwnedContentShortfall"},{"type":"null"}]}},"type":"object","required":["bucket","url","page_title","citation_count","query_matches","weak","context","topic_volume","demand_prompt","difficulty","topic_demand","facets","sub_question_coverage","shortfall"],"title":"OwnedContentPage"},"OwnedContentShortfall":{"properties":{"checks":{"items":{"$ref":"#/components/schemas/OwnedContentShortfallCheck"},"type":"array","maxItems":5,"title":"Checks"},"rival_urls":{"items":{"type":"string"},"type":"array","maxItems":3,"title":"Rival Urls"}},"type":"object","required":["checks","rival_urls"],"title":"OwnedContentShortfall","description":"Where a page falls short of the rival pages cited on the same prompts.\n\n`rival_urls` names what the comparison ran against, so a reader can open\nthe pages the answer preferred. Empty means only the checks that need no\nrival could be made."},"OwnedContentShortfallCheck":{"properties":{"key":{"type":"string","enum":["freshness","depth","structure","sub_questions","technical"],"title":"Key"},"short":{"type":"boolean","title":"Short","default":false},"detail":{"type":"string","title":"Detail","default":""}},"type":"object","required":["key","short","detail"],"title":"OwnedContentShortfallCheck","description":"A stored check under \"where it falls short\".\n\n`detail` is the sentence the pane renders; `short` is whether it is a\nfinding. The older keys remain valid for historical reads. A check absent\nfrom the list was not measurable, which differs from a passed check."},"OwnedContentStrategySection":{"properties":{"status":{"type":"string","enum":["ready","processing","failed","unavailable"],"title":"Status"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headline"},"total_crawled_pages":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Crawled Pages"},"cited_strong_pages":{"items":{"$ref":"#/components/schemas/OwnedContentPage"},"type":"array","title":"Cited Strong Pages"},"improve_pages":{"items":{"$ref":"#/components/schemas/OwnedContentPage"},"type":"array","title":"Improve Pages"},"create_recommendations":{"items":{"$ref":"#/components/schemas/OwnedContentCreate"},"type":"array","title":"Create Recommendations"},"cited_query_matches":{"items":{"type":"string"},"type":"array","title":"Cited Query Matches"},"improve_query_matches":{"items":{"type":"string"},"type":"array","title":"Improve Query Matches"},"cited_strong_total":{"type":"integer","title":"Cited Strong Total","description":"Owned pages with strong citation performance.","default":0},"improve_total":{"type":"integer","title":"Improve Total","description":"All owned pages to improve before paging.","default":0},"create_total":{"type":"integer","title":"Create Total","description":"All suggested topics to create before paging.","default":0},"crawl_page_promise":{"type":"integer","title":"Crawl Page Promise","default":150},"pages_judged":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages Judged"},"missing_state":{"type":"string","enum":["ready","not_read"],"title":"Missing State","default":"ready"},"unread_locales":{"items":{"type":"string"},"type":"array","title":"Unread Locales"},"pages_read":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages Read"},"pages_found":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages Found"},"not_read_line":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Not Read Line"},"owned_citation_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Owned Citation Total","description":"Citations to the brand's owned pages."},"mapped_citation_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mapped Citation Total","description":"Citations mapped to an owned page."},"mapped_page_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mapped Page Count","description":"Owned pages mapped to a topic."}},"additionalProperties":false,"type":"object","required":["status","message","headline","total_crawled_pages","cited_strong_pages","improve_pages","create_recommendations","cited_query_matches","improve_query_matches","cited_strong_total","improve_total","create_total","crawl_page_promise","pages_judged","missing_state","unread_locales","pages_read","pages_found","not_read_line","owned_citation_total","mapped_citation_total","mapped_page_count"],"title":"OwnedContentStrategySection"},"OwnedDomainsDraft":{"properties":{"derived":{"items":{"type":"string"},"type":"array","title":"Derived"},"proposed":{"items":{"type":"string"},"type":"array","title":"Proposed"},"confirmed":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Confirmed"},"dismissed":{"items":{"type":"string"},"type":"array","title":"Dismissed","default":[]}},"type":"object","required":["derived","proposed","confirmed","dismissed"],"title":"OwnedDomainsDraft","description":"The review gate over which domains count as this brand's own."},"PageCrawlerBot":{"properties":{"bot":{"type":"string","title":"Bot"},"operator":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operator"},"category":{"anyOf":[{"type":"string","enum":["training","ai_search","user_fetch","search_engine"]},{"type":"null"}],"title":"Category"},"hits":{"type":"integer","title":"Hits"}},"type":"object","required":["bot","operator","category","hits"],"title":"PageCrawlerBot","description":"One bot's served requests for one page over the recorded crawler window."},"PageFunnel":{"properties":{"window":{"anyOf":[{"$ref":"#/components/schemas/PageFunnelWindow"},{"type":"null"}],"description":"28 whole days ending two days before the newest pinned weekly scan started. Independent of period and figure filters. Null without a weekly scan."},"sources":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Sources","description":"Crawler sources recorded for window. Null without a crawler measurement."},"crawler_bots":{"anyOf":[{"items":{"$ref":"#/components/schemas/PageCrawlerBot"},"type":"array"},{"type":"null"}],"title":"Crawler Bots","description":"Per-bot served requests in window, verified true or unknown, including search engines. Categories come from the frozen measurement. Null when this page is unmeasured; empty when no requests qualify."},"search_clicks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Clicks","description":"Search Console clicks in window. Null without a complete read of the current property returning this page for that window."},"search_impressions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Impressions","description":"Search Console impressions in window. Null without a complete read of the current property returning this page for that window."},"crawled":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Crawled","description":"Served training and AI-search requests in window, verified true or unknown. Plugin counts are a floor. Null when this page is unmeasured."},"fetched_live":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fetched Live","description":"Served user-fetch requests in window, verified true or unknown. Plugin counts are a floor. Null when this page is unmeasured."},"cited":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cited","description":"Frozen citations with default filters from weekly scans completed inside window. Null without scans or with incomplete citation evidence."},"ai_visits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ai Visits","description":"Visits from AI attributed by GA4 in window, a floor because visits often carry no referrer. Null without a complete read of the current property covering this page for that window."},"blocked":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Blocked","description":"Blocked requests from AI categories in window, across all verification states. Plugin counts are a floor. Null when unmeasured."},"not_found":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Not Found","description":"Not-found requests from AI categories in window, across all verification states. Plugin counts are a floor. Null when unmeasured."},"unverified":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Unverified","description":"Known-unverified requests from AI categories in window, across all outcomes. Unknown verification does not count here. Plugin counts are a floor. Null when unmeasured."},"search_engine_crawls":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Engine Crawls","description":"Served search-engine requests in window, verified true or unknown. Plugin counts are a floor. Null when this page is unmeasured."}},"type":"object","required":["window","sources","crawler_bots","search_clicks","search_impressions","crawled","fetched_live","cited","ai_visits","blocked","not_found","unverified","search_engine_crawls"],"title":"PageFunnel"},"PageFunnelPoint":{"properties":{"start":{"type":"string","format":"date","title":"Start","description":"First day of the scan's 28-day window, inclusive."},"end":{"type":"string","format":"date","title":"End","description":"Last day of the scan's 28-day window, inclusive."},"search_clicks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Clicks"},"crawled":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Crawled"},"fetched_live":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fetched Live"},"cited":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cited"},"ai_visits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ai Visits"}},"type":"object","required":["start","end","search_clicks","crawled","fetched_live","cited","ai_visits"],"title":"PageFunnelPoint","description":"The funnel on one weekly scan's window. Each value is null on the same\nterms as the funnel's."},"PageFunnelWindow":{"properties":{"start":{"type":"string","format":"date","title":"Start","description":"First day of the funnel window, inclusive."},"end":{"type":"string","format":"date","title":"End","description":"Last day of the funnel window, inclusive."},"history_days":{"type":"integer","title":"History Days","description":"Days back from today that the plan reads crawler, visit and search measurements."},"clamped":{"type":"boolean","title":"Clamped","description":"True when the weekly scan this window belongs to completed before that history began. Crawler, visit and search measurements are then null."}},"type":"object","required":["start","end","history_days","clamped"],"title":"PageFunnelWindow"},"PageTake":{"properties":{"answer_read_id":{"type":"string","title":"Answer Read Id"},"prompt_uid":{"type":"string","title":"Prompt Uid"},"prompt_text":{"type":"string","title":"Prompt Text"},"engine_id":{"type":"string","title":"Engine Id"},"segment":{"$ref":"#/components/schemas/AnswerReadSegment"},"read_at":{"type":"string","title":"Read At"},"states":{"$ref":"#/components/schemas/AnswerReadStates"},"claim":{"type":"string","title":"Claim"},"passage":{"type":"string","title":"Passage"}},"type":"object","required":["answer_read_id","prompt_uid","prompt_text","engine_id","segment","read_at","states","claim","passage"],"title":"PageTake","description":"One answer's take from one page."},"PageTakeList":{"properties":{"items":{"items":{"$ref":"#/components/schemas/PageTake"},"type":"array","title":"Items"},"total":{"type":"integer","minimum":0.0,"title":"Total"},"limit":{"type":"integer","minimum":1.0,"title":"Limit"},"offset":{"type":"integer","minimum":0.0,"title":"Offset"},"has_more":{"type":"boolean","title":"Has More","default":false},"pending":{"type":"integer","minimum":0.0,"title":"Pending","default":0},"unavailable":{"type":"integer","minimum":0.0,"title":"Unavailable","default":0},"rejected":{"type":"integer","minimum":0.0,"title":"Rejected","default":0}},"type":"object","required":["items","total","limit","offset","has_more","pending","unavailable","rejected"],"title":"PageTakeList","description":"Newest read first. `total` counts the supported takes; `pending` counts\nthe current matches whose support has not been decided yet, `rejected` the\nones Jev said the passage does not support, and `unavailable` the citing\ncells whose evidence could not be kept. None of the three is in `items` or\n`total`."},"PairedChange":{"properties":{"delta":{"type":"number","title":"Delta","description":"The move in points: the shown value minus the baseline's, both as the trend draws them, or both over `compared_engines` where it names engines. Null when the baseline has no value."},"low":{"type":"number","title":"Low","description":"The lower end of the paired test's 95% range for the move, in points."},"high":{"type":"number","title":"High","description":"The upper end of the paired test's 95% range for the move, in points."},"real":{"type":"boolean","title":"Real","description":"Whether the paired test over the prompt × engine cells both reads measured says the figure moved. The state is up or down only when this is true and the move has the sign of `delta`; otherwise it is steady and carries the signed `delta`."},"compared_engines":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Compared Engines","description":"The engines `delta` was sized on, when the baseline report asked other engines than the current period. The value and the trend still include every engine asked. Null when the size is the move the trend draws."}},"type":"object","required":["delta","low","high","real","compared_engines"],"title":"PairedChange","description":"A figure's change over the selected window, in points, with its 95%\nrange. `delta` is the shown value minus the baseline's, as the trend draws\nthem or over `compared_engines`; `real` is whether the paired test over the\nprompt × engine cells both reads measured says it moved. A surface\nannounces a direction only for a real change that has the sign of `delta`."},"PaneAction":{"properties":{"id":{"type":"string","title":"Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"},"status":{"type":"string","title":"Status"},"expected_impact_pts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expected Impact Pts","description":"Always null."},"impact_scale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Impact Scale"}},"type":"object","required":["id","title","detail","status","expected_impact_pts","impact_scale"],"title":"PaneAction","description":"The response the rival already has queued, as the pane shows it."},"PanePrompt":{"properties":{"query_id":{"type":"string","title":"Query Id"},"prompt_uid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Uid"},"text":{"type":"string","title":"Text"},"intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent"},"prompt_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Type"},"search_volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Volume"},"winner_brand_keys":{"items":{"type":"string"},"type":"array","title":"Winner Brand Keys"},"answer_read_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Answer Read Id"}},"type":"object","required":["query_id","prompt_uid","text","intent","prompt_type","search_volume","winner_brand_keys","answer_read_id"],"title":"PanePrompt"},"PerceptionAxisFigure":{"properties":{"axis":{"type":"string","title":"Axis"},"label":{"type":"string","title":"Label"},"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value"},"numerator":{"type":"number","title":"Numerator"},"denominator":{"type":"integer","title":"Denominator"},"measured":{"type":"boolean","title":"Measured"},"low":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Low"},"high":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"High"},"figure":{"$ref":"#/components/schemas/MetricFigure","readOnly":true}},"type":"object","required":["axis","label","value","numerator","denominator","measured","low","high","figure"],"title":"PerceptionAxisFigure","description":"One axis's weighted percentage, range and measured population."},"PerceptionPromptCell":{"properties":{"engine_id":{"type":"string","title":"Engine Id"},"strength":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Strength"},"mentioned":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Mentioned"},"understood":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Understood"},"recommended":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Recommended"},"praised":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Praised"},"sentiment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sentiment"},"cited":{"type":"boolean","title":"Cited"},"answer_read_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Answer Read Id"},"icon_states":{"$ref":"#/components/schemas/IconStates","readOnly":true}},"type":"object","required":["engine_id","strength","mentioned","understood","recommended","praised","sentiment","cited","answer_read_id","icon_states"],"title":"PerceptionPromptCell","description":"One prompt on one engine, with the four states that read (D32, D37).\n\n`praised` is the axis reading — whether this answer frames the brand\npositively — and `sentiment` is the framing itself. The page needs both:\nthe mood a cell shows has three states, and a neutral read and a critical\none are both `praised: false`."},"PerceptionPromptRow":{"properties":{"key":{"type":"string","title":"Key"},"query_id":{"type":"string","title":"Query Id"},"text":{"type":"string","title":"Text"},"intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent"},"prompt_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Type"},"search_volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Volume"},"cells":{"items":{"$ref":"#/components/schemas/PerceptionPromptCell"},"type":"array","title":"Cells"}},"type":"object","required":["key","query_id","text","intent","prompt_type","search_volume","cells"],"title":"PerceptionPromptRow","description":"A prompt every screen that lists prompts refers to by key, so the\nthirty-four rows are serialised once rather than once per axis."},"PerceptionSeriesPoint":{"properties":{"at":{"type":"string","title":"At"},"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value"},"measured_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Measured Domain"},"key":{"anyOf":[{"$ref":"#/components/schemas/ComparabilityKey"},{"type":"null"}]},"breaks":{"items":{"$ref":"#/components/schemas/KeyChange"},"type":"array","title":"Breaks","default":[]},"prompts_changed":{"type":"boolean","title":"Prompts Changed","default":false},"break":{"anyOf":[{"$ref":"#/components/schemas/TrendBreak"},{"type":"null"}],"readOnly":true}},"type":"object","required":["at","value","measured_domain","key","breaks","prompts_changed","break"],"title":"PerceptionSeriesPoint"},"PeriodDescriptor":{"properties":{"preset":{"type":"string","enum":["1w","4w","12w","all"],"title":"Preset"},"reports":{"type":"integer","title":"Reports"},"first_answer_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Answer At"},"last_answer_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Answer At"},"excluded_reports":{"type":"integer","title":"Excluded Reports"}},"type":"object","required":["preset","reports","first_answer_at","last_answer_at","excluded_reports"],"title":"PeriodDescriptor"},"PersonaBox":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"fields":{"additionalProperties":true,"type":"object","title":"Fields"},"ai_generated":{"type":"boolean","title":"Ai Generated"},"is_general_buyer":{"type":"boolean","title":"Is General Buyer"},"segments":{"items":{"$ref":"#/components/schemas/PersonaSegmentRow"},"type":"array","title":"Segments"},"shift":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shift"}},"type":"object","required":["id","name","description","fields","ai_generated","is_general_buyer","segments","shift"],"title":"PersonaBox","description":"One asker, and the segments that ask as it.\n\n`id` is None on the general buyer, which is the absence of a persona rather\nthan a row in the library (D47), so it carries no fields and cannot be\nedited or removed."},"PersonaSegmentRow":{"properties":{"id":{"type":"string","title":"Id"},"label":{"type":"string","title":"Label"},"name":{"type":"string","title":"Name"},"is_default":{"type":"boolean","title":"Is Default"}},"type":"object","required":["id","label","name","is_default"],"title":"PersonaSegmentRow"},"PieceConstraints":{"properties":{"words":{"anyOf":[{"$ref":"#/components/schemas/WordBand"},{"type":"null"}],"description":"The length asked for, in words."},"links":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Links","description":"How many links the piece carries, where asked."},"deadline":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Deadline","description":"When the piece is needed by."}},"type":"object","required":["words","links","deadline"],"title":"PieceConstraints","description":"What the order asks of the piece: its length in words, the links it\ncarries and the date it is needed by."},"Placement":{"properties":{"industry":{"type":"string","title":"Industry"},"label":{"type":"string","title":"Label"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score"},"ranked":{"type":"integer","title":"Ranked","default":0}},"type":"object","required":["industry","label","rank","score","ranked"],"title":"Placement"},"PlacementSides":{"properties":{"ai":{"$ref":"#/components/schemas/SideStanding","description":"The brand's place and score on the AI board."},"search":{"anyOf":[{"$ref":"#/components/schemas/SideStanding"},{"type":"null"}],"description":"Place and score on Search; null where no Search score is available."}},"type":"object","required":["ai","search"],"title":"PlacementSides"},"PlacementsRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"rows":{"items":{"$ref":"#/components/schemas/BrandPlacement"},"type":"array","title":"Rows"}},"type":"object","required":["meta","next_cursor","total","limit","offset","rows"],"title":"PlacementsRead"},"PlanFeatures":{"properties":{"mentions_monitoring":{"type":"boolean","title":"Mentions Monitoring","description":"Whether the plan includes Mentions monitoring."},"reviews":{"type":"boolean","title":"Reviews","description":"Whether the plan includes Reviews."},"advocacy":{"type":"boolean","title":"Advocacy","description":"Whether the plan includes Advocacy."}},"type":"object","required":["mentions_monitoring","reviews","advocacy"],"title":"PlanFeatures","description":"The Plus-only parts a read can carry, which a plan without them answers\nwith their empty value rather than a refusal."},"PortfolioAxis":{"properties":{"axis":{"type":"string","title":"Axis"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"change":{"anyOf":[{"$ref":"#/components/schemas/PairedChange"},{"type":"null"}]}},"type":"object","required":["axis","value","change"],"title":"PortfolioAxis","description":"One axis of one brand over the last week, with its move.\n\n`value` is null where the week could not measure the axis — a gap, not a\nzero. `change` is the figures read's paired change and is null where no\nearlier week was read: a first read has moved from nothing."},"PortfolioBrandRow":{"properties":{"brand_id":{"type":"string","title":"Brand Id"},"domain":{"type":"string","title":"Domain"},"data_as_of":{"anyOf":[{"$ref":"#/components/schemas/DataAsOf"},{"type":"null"}]},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score"},"score_change":{"anyOf":[{"$ref":"#/components/schemas/PairedChange"},{"type":"null"}]},"axes":{"items":{"$ref":"#/components/schemas/PortfolioAxis"},"type":"array","title":"Axes","default":[]},"actions_waiting":{"type":"integer","title":"Actions Waiting","default":0},"movement_since_deep_read":{"type":"integer","title":"Movement Since Deep Read","default":0},"score_band":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Score Band","description":"The band `score` falls in, so the row names it; null without a score.","readOnly":true}},"type":"object","required":["brand_id","domain","data_as_of","score","score_change","axes","actions_waiting","movement_since_deep_read","score_band"],"title":"PortfolioBrandRow","description":"One brand of the portfolio table."},"PortfolioManagedAccount":{"properties":{"organization_id":{"type":"string","title":"Organization Id"},"name":{"type":"string","title":"Name"}},"type":"object","required":["organization_id","name"],"title":"PortfolioManagedAccount","description":"The managed account a manager portfolio row belongs to: the table's\naccount column and the key its account filter uses."},"PositionCounts":{"properties":{"top_3":{"type":"integer","title":"Top 3","description":"Keywords with a best rank of 1 to 3.","default":0},"top_4_10":{"type":"integer","title":"Top 4 10","description":"Keywords with a best rank of 4 to 10.","default":0},"not_in_top_10":{"type":"integer","title":"Not In Top 10","description":"Fetched keywords with none of your pages in the ten.","default":0},"unchecked":{"type":"integer","title":"Unchecked","description":"Keywords without a fetched check.","default":0}},"type":"object","required":["top_3","top_4_10","not_in_top_10","unchecked"],"title":"PositionCounts"},"PriceEstimate":{"properties":{"low":{"type":"integer","title":"Low","description":"The low end of the estimate, in whole units."},"high":{"type":"integer","title":"High","description":"The high end of the estimate, in whole units."},"currency":{"type":"string","const":"EUR","title":"Currency","description":"Its currency, always EUR.","default":"EUR"}},"type":"object","required":["low","high","currency"],"title":"PriceEstimate"},"ProReportExtras":{"properties":{"third_party_opportunities":{"$ref":"#/components/schemas/ThirdPartyOpportunitySection"},"sentiment_matrix":{"$ref":"#/components/schemas/SentimentSection"},"competitor_content_evidence":{"$ref":"#/components/schemas/CompetitorContentEvidenceSection"},"owned_content_strategy":{"$ref":"#/components/schemas/OwnedContentStrategySection"},"pdf_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pdf Url"},"cell_strength_stddev_pts":{"additionalProperties":{"type":"number"},"type":"object","title":"Cell Strength Stddev Pts"}},"additionalProperties":false,"type":"object","required":["third_party_opportunities","sentiment_matrix","competitor_content_evidence","owned_content_strategy","pdf_url","cell_strength_stddev_pts"],"title":"ProReportExtras"},"Problem":{"properties":{"type":{"type":"string","title":"Type"},"title":{"type":"string","title":"Title"},"status":{"type":"integer","title":"Status"},"detail":{"type":"string","title":"Detail"},"code":{"type":"string","title":"Code"},"instance":{"type":"string","title":"Instance","default":""}},"type":"object","required":["type","title","status","detail","code","instance"],"title":"Problem","description":"An RFC 9457 problem linking its code to human-readable documentation."},"ProductCardEngine":{"properties":{"engine":{"type":"string","title":"Engine","description":"The answering engine."},"state":{"type":"string","enum":["read","not_read","not_measured"],"title":"State","description":"Read once any answer's cards were captured; otherwise not read or unsupported."},"yours":{"type":"integer","title":"Yours","description":"Read questions showing at least one of your products."},"with_cards":{"type":"integer","title":"With Cards","description":"Read questions showing organic product cards."}},"type":"object","required":["engine","state","yours","with_cards"],"title":"ProductCardEngine"},"ProductCardQuestion":{"properties":{"weeks":{"type":"integer","title":"Weeks","description":"Weekly reports counted from the period measured as ecommerce.","default":0},"state":{"type":"string","enum":["read","not_read","not_measured"],"title":"State","description":"Read, capture failed or no answers yet, or unsupported."},"products":{"type":"integer","title":"Products","description":"Distinct organic products across the question's read answers."},"yours":{"type":"integer","title":"Yours","description":"How many of those distinct products belong to your brand."},"best":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best","description":"The lowest place of one of your organic cards."},"id":{"type":"string","title":"Id","description":"The question's prompt id, or query id for a Snapshot."}},"type":"object","required":["weeks","state","products","yours","best","id"],"title":"ProductCardQuestion"},"ProductCardRank":{"properties":{"position":{"type":"integer","title":"Position","description":"One plus the number of brands with a higher share."},"of":{"type":"integer","title":"Of","description":"You and your tracked competitors, once per canonical brand."}},"type":"object","required":["position","of"],"title":"ProductCardRank"},"ProductCardStrip":{"properties":{"total":{"type":"integer","title":"Total","description":"Unbranded tracked questions counted by the strip."},"yours":{"type":"integer","title":"Yours","description":"Read questions showing your products."},"others_only":{"type":"integer","title":"Others Only","description":"Read questions showing products, none yours."},"no_cards":{"type":"integer","title":"No Cards","description":"Read questions with no organic product cards."},"not_read":{"type":"integer","title":"Not Read","description":"Questions with no product-card reading."}},"type":"object","required":["total","yours","others_only","no_cards","not_read"],"title":"ProductCardStrip"},"ProductCardsCell":{"properties":{"weeks":{"type":"integer","title":"Weeks","description":"Weekly reports counted from the period measured as ecommerce.","default":0},"state":{"type":"string","enum":["read","not_read","not_measured"],"title":"State","description":"Read, capture failed or no answers yet, or unsupported."},"products":{"type":"integer","title":"Products","description":"Distinct organic products across the question's read answers."},"yours":{"type":"integer","title":"Yours","description":"How many of those distinct products belong to your brand."},"best":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best","description":"The lowest place of one of your organic cards."}},"type":"object","required":["weeks","state","products","yours","best"],"title":"ProductCardsCell"},"ProductLineResponse":{"properties":{"name":{"type":"string","title":"Name"},"category":{"type":"string","title":"Category"},"target_buyer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Buyer"}},"type":"object","required":["name","category","target_buyer"],"title":"ProductLineResponse"},"ProductLineView":{"properties":{"name":{"type":"string","title":"Name"},"category":{"type":"string","title":"Category"},"target_buyer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Buyer"}},"type":"object","required":["name","category","target_buyer"],"title":"ProductLineView"},"ProductQuestionStrip":{"properties":{"total":{"type":"integer","title":"Total","description":"Unbranded tracked questions under the figure filters."},"yours":{"type":"integer","title":"Yours","description":"Questions whose read answers showed one of your products."},"others":{"type":"integer","title":"Others","description":"Questions with organic cards but none of your products."},"none":{"type":"integer","title":"None","description":"Questions whose cards were read with no organic cards shown."},"not_read":{"type":"integer","title":"Not Read","description":"Questions with no answer whose cards were read."},"questions":{"anyOf":[{"items":{"$ref":"#/components/schemas/ProductStripQuestion"},"type":"array"},{"type":"null"}],"title":"Questions","description":"Every counted question, grouped yours, others, none, not read; null above 30."}},"type":"object","required":["total","yours","others","none","not_read","questions"],"title":"ProductQuestionStrip"},"ProductStripQuestion":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The tracked question's prompt id."},"text":{"type":"string","title":"Text","description":"The question's current wording."},"group":{"type":"string","enum":["yours","others","none","not_read"],"title":"Group","description":"Classification across its read answers only."}},"type":"object","required":["id","text","group"],"title":"ProductStripQuestion"},"ProfileClaim":{"properties":{"axis":{"type":"string","title":"Axis"},"label":{"type":"string","title":"Label"},"field":{"type":"string","title":"Field"},"intended":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intended"},"measured":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Measured"},"ai_reads":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ai Reads"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"answers":{"type":"integer","title":"Answers"},"engines":{"type":"integer","title":"Engines"},"agrees":{"type":"integer","title":"Agrees"},"partial":{"type":"integer","title":"Partial"},"diverges":{"type":"integer","title":"Diverges"},"absent":{"type":"integer","title":"Absent"}},"type":"object","required":["axis","label","field","intended","measured","ai_reads","score","answers","engines","agrees","partial","diverges","absent"],"title":"ProfileClaim","description":"One claim, as the profile states it and as the engines read it back."},"Progress":{"properties":{"done":{"type":"integer","title":"Done","description":"Units completed."},"total":{"type":"integer","title":"Total","description":"Units expected."},"unit":{"type":"string","title":"Unit","description":"The counted unit, such as answers or pages."}},"type":"object","required":["done","total","unit"],"title":"Progress"},"PromptCell":{"properties":{"engine_id":{"type":"string","title":"Engine Id"},"display_name":{"type":"string","title":"Display Name"},"state":{"type":"string","enum":["leading","recommended","mentioned","weak","absent","unmeasured"],"title":"State"},"answer_read_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Answer Read Id"},"winner":{"type":"string","enum":["you","rival","none","unmeasured"],"title":"Winner","default":"unmeasured"},"days":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Days"}},"type":"object","required":["engine_id","display_name","state","answer_read_id","winner","days"],"title":"PromptCell"},"PromptChange":{"properties":{"direction":{"type":"string","enum":["up","down","flat","new"],"title":"Direction"},"label":{"type":"string","title":"Label"},"engines":{"items":{"type":"string"},"type":"array","title":"Engines"}},"type":"object","required":["direction","label","engines"],"title":"PromptChange","description":"The change column, in words (D31: a row never carries a spark)."},"PromptCompetitor":{"properties":{"brand_key":{"type":"string","title":"Brand Key"},"brand_name":{"type":"string","title":"Brand Name"},"is_you":{"type":"boolean","title":"Is You"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"answers":{"type":"integer","title":"Answers","default":0},"heralded_score":{"$ref":"#/components/schemas/Figure"},"mentioned":{"$ref":"#/components/schemas/Figure"},"recommended":{"$ref":"#/components/schemas/Figure"},"trend":{"$ref":"#/components/schemas/PromptTrend"}},"type":"object","required":["brand_key","brand_name","is_you","domain","answers","heralded_score","mentioned","recommended","trend"],"title":"PromptCompetitor","description":"A brand the prompt's answers name, of the brand and its tracked\ncompetitors, on the same answers as the prompt's own figures. `answers`\ncounts those answers, which a figure's denominator may leave some of out,\nas Mentioned does a Brand-type prompt's."},"PromptEngineCard":{"properties":{"engine_id":{"type":"string","title":"Engine Id"},"display_name":{"type":"string","title":"Display Name"},"score":{"$ref":"#/components/schemas/ScoreMark"},"figures":{"items":{"$ref":"#/components/schemas/ScoreMark"},"type":"array","title":"Figures"},"trend":{"items":{"$ref":"#/components/schemas/FigurePoint"},"type":"array","title":"Trend"},"mentioned_count":{"type":"integer","title":"Mentioned Count","description":"Answers on this engine that mention the brand, over the `answers` of the Mentioned figure in `figures`; 0 where that figure has no answers."},"recommended_count":{"type":"integer","title":"Recommended Count","description":"Answers on this engine that recommend the brand, over the `answers` of the Recommended figure in `figures`; 0 where that figure has no answers."}},"type":"object","required":["engine_id","display_name","score","figures","trend","mentioned_count","recommended_count"],"title":"PromptEngineCard","description":"One engine's figures on the prompt. `figures` is Mentioned,\nRecommended, Understood and Praised, each banded by its own value."},"PromptFilterOption":{"properties":{"value":{"type":"string","title":"Value"},"label":{"type":"string","title":"Label"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["value","label","count"],"title":"PromptFilterOption"},"PromptFilters":{"properties":{"types":{"items":{"$ref":"#/components/schemas/PromptFilterOption"},"type":"array","title":"Types"},"intents":{"items":{"$ref":"#/components/schemas/PromptFilterOption"},"type":"array","title":"Intents"},"topics":{"items":{"$ref":"#/components/schemas/PromptFilterOption"},"type":"array","title":"Topics"}},"type":"object","required":["types","intents","topics"],"title":"PromptFilters","description":"Topic, type and intent choices counted over every tracked question."},"PromptHealth":{"properties":{"stage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stage","description":"learn, evaluate or buy, derived from the intent."},"rate":{"type":"number","title":"Rate","description":"The share of `weeks`' answers naming any company."},"weeks":{"items":{"$ref":"#/components/schemas/HealthWeek"},"type":"array","title":"Weeks","description":"The last measured weeks, oldest first."},"threshold":{"type":"number","title":"Threshold","default":0.15},"low_signal":{"type":"boolean","title":"Low Signal","description":"An evaluate or buy prompt under the threshold in each of its last 4 measured weeks. Never true for a learn prompt."}},"type":"object","required":["stage","rate","weeks","threshold","low_signal"],"title":"PromptHealth","description":"How often the prompt's answers name any company, over its last measured weeks."},"PromptTile":{"properties":{"pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pct"},"numerator":{"type":"number","title":"Numerator"},"denominator":{"type":"integer","title":"Denominator"},"explorer_filter":{"additionalProperties":{"type":"string"},"type":"object","title":"Explorer Filter"},"answer_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Answer Count","description":"Answers supporting this prompt or evidence row, or null when no count applies."},"state":{"anyOf":[{"type":"string","x-extensible-enum":["measured","too_few_answers","calibrating","first_report","not_comparable","not_measured","pending","not_scored"]},{"type":"string","const":"not_applicable"}],"title":"State","description":"Measurement state; not_applicable for Mentioned and Recommended on Brand prompts.","default":"not_measured"}},"type":"object","required":["pct","numerator","denominator","explorer_filter","answer_count"],"title":"PromptTile"},"PromptTrend":{"properties":{"state":{"type":"string","enum":["up","down","steady","not_comparable","calibrating","new","none"],"title":"State"},"delta":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Delta"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"}},"type":"object","required":["state","delta","label"],"title":"PromptTrend","description":"A score's change, as the Trend column and the pane state it."},"PromptsRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"rows":{"items":{"$ref":"#/components/schemas/LeaderboardPromptRow"},"type":"array","title":"Rows"}},"type":"object","required":["meta","next_cursor","total","limit","offset","rows"],"title":"PromptsRead"},"ProposedContact":{"properties":{"address":{"type":"string","title":"Address","description":"Their address."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Their name, where the reply gave one."}},"type":"object","required":["address","name"],"title":"ProposedContact","description":"Another person a reply named to write to."},"PublishedPrice":{"properties":{"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"The price the site publishes, exactly as written, such as 99.90."},"currency":{"type":"string","title":"Currency","description":"Its ISO 4217 currency code."}},"type":"object","required":["amount","currency"],"title":"PublishedPrice"},"QuestionCompetitor":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"}},"type":"object","required":["name","slug","domain"],"title":"QuestionCompetitor"},"QuotedLine":{"properties":{"verdict":{"type":"string","enum":["agrees","partly","contradicts","doesnt_say"],"title":"Verdict","description":"How the quoted answer addresses the claim."},"quote":{"type":"string","title":"Quote","description":"A verbatim passage from the measured evidence."},"count":{"type":"integer","title":"Count","description":"The number of measured answers this passage represents."},"engine_id":{"type":"string","title":"Engine Id","description":"The engine that supplied the answer."},"prompt_uid":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Prompt Uid","description":"The stored question identifier; null when this evidence has no linked question."},"answer_read_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Answer Read Id","description":"The stored answer identifier that opens this quotation; null when unavailable."},"asked_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asked Language","description":"The language the engine was asked in; null when unknown."},"language":{"type":"string","title":"Language","description":"The content’s language code, or unknown when undetermined.","default":"unknown"}},"type":"object","required":["verdict","quote","count","engine_id","prompt_uid","answer_read_id","asked_language","language"],"title":"QuotedLine","description":"One answer's words on a claim, and how many answers reached its verdict."},"Race":{"properties":{"cohort":{"type":"string","enum":["run","roster"],"title":"Cohort"},"average":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Average"},"rows":{"items":{"$ref":"#/components/schemas/RaceRow"},"type":"array","title":"Rows"}},"type":"object","required":["cohort","average","rows"],"title":"Race","description":"The brand and its rivals by Heralded Score, best first, with the\nrivals' average. Brands on the same score share a place, ordered by name;\nan unmeasured subject comes last, unranked."},"RaceRow":{"properties":{"brand_name":{"type":"string","title":"Brand Name"},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"},"is_subject":{"type":"boolean","title":"Is Subject"},"named_in_answers":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Named In Answers"},"total_answers":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Answers"},"domain_cite_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Domain Cite Count","description":"Citations to this brand's domain."},"gap_pts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Gap Pts","description":"This brand's Heralded Score minus the subject's score. Null if either is unmeasured."}},"type":"object","required":["brand_name","score","rank","is_subject","named_in_answers","total_answers","domain_cite_count","gap_pts"],"title":"RaceRow","description":"One brand on the race: its Heralded Score, its place among the race's\nbrands, and the answers that named it and cited its domain. A subject the\nread could not measure has no score and no place."},"RankChangeRow":{"properties":{"brand_id":{"type":"string","format":"uuid","title":"Brand Id"},"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"previous_rank":{"type":"integer","title":"Previous Rank"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"},"rank_change":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank Change"},"state":{"type":"string","enum":["ranked","unranked","not_on_roster"],"title":"State"}},"type":"object","required":["brand_id","name","slug","domain","previous_rank","rank","rank_change","state"],"title":"RankChangeRow"},"RankChangesRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"rows":{"items":{"$ref":"#/components/schemas/RankChangeRow"},"type":"array","title":"Rows"}},"type":"object","required":["meta","next_cursor","total","limit","offset","rows"],"title":"RankChangesRead"},"RankScorePoint":{"properties":{"month":{"type":"string","title":"Month"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score"},"state":{"type":"string","enum":["ranked","unranked","missing","not_on_roster"],"title":"State"}},"type":"object","required":["month","rank","score","state"],"title":"RankScorePoint"},"RankedRate":{"properties":{"value":{"type":"integer","title":"Value"},"low":{"type":"integer","title":"Low"},"high":{"type":"integer","title":"High"},"k":{"type":"integer","title":"K"},"n":{"type":"integer","title":"N"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"},"rank_of":{"type":"integer","title":"Rank Of"},"cohort":{"type":"string","enum":["run","roster"],"title":"Cohort"},"change":{"anyOf":[{"$ref":"#/components/schemas/PairedChange"},{"type":"null"}]}},"type":"object","required":["value","low","high","k","n","rank","rank_of","cohort","change"],"title":"RankedRate","description":"Mentioned or Recommended: the rate in points with its 95% range, the\nk of n answers it counts, and the brand's place among the rivals `cohort`\nnames: those the run scored (`run`) or those tracked today (`roster`).\n\nBrands on the same figure share a place. `rank` is None where no answer\ncounted the brand, because that place would be shared with every brand no\nanswer counted; `rank_of` counts the brand and every rival measured."},"RateLimitProblem":{"properties":{"type":{"type":"string","title":"Type"},"title":{"type":"string","title":"Title"},"status":{"type":"integer","title":"Status"},"detail":{"type":"string","title":"Detail"},"code":{"type":"string","title":"Code"},"instance":{"type":"string","title":"Instance","default":""},"rate_limit":{"$ref":"#/components/schemas/RateLimitValues"}},"type":"object","required":["type","title","status","detail","code","instance","rate_limit"],"title":"RateLimitProblem"},"RateLimitValues":{"properties":{"limit":{"type":"integer","title":"Limit"},"window":{"type":"integer","title":"Window"},"remaining":{"type":"integer","title":"Remaining"},"reset":{"type":"integer","title":"Reset"}},"type":"object","required":["limit","window","remaining","reset"],"title":"RateLimitValues"},"ReadabilityCheck":{"properties":{"id":{"type":"string","title":"Id"},"label":{"type":"string","title":"Label"},"target":{"type":"string","title":"Target"},"measured":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Measured"},"met":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Met"},"pages_in_scope":{"type":"integer","title":"Pages In Scope"},"fix":{"items":{"type":"string"},"type":"array","title":"Fix","description":"Steps to fix a failing check, if available."},"group":{"type":"string","enum":["reach","understand","fast","trust"],"title":"Group","description":"Which readability group this check belongs to.","readOnly":true}},"type":"object","required":["id","label","target","measured","met","pages_in_scope","fix","group"],"title":"ReadabilityCheck"},"RecipientDiscovery":{"properties":{"outcome":{"type":"string","enum":["unreadable","searched_none","found"],"title":"Outcome","description":"Whether the source was unreadable, searched without an address, or yielded an address."},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"A customer-facing reason for a missing address; null when an address was found."}},"type":"object","required":["outcome","message"],"title":"RecipientDiscovery"},"RecipientRefusal":{"properties":{"address":{"type":"string","title":"Address","description":"The refused address."},"reason":{"type":"string","enum":["opt_out","hard_bounce"],"title":"Reason","description":"They asked not to be contacted, or the address bounced for good."},"on":{"type":"string","format":"date","title":"On","description":"When it was refused."},"message":{"type":"string","title":"Message","description":"The refusal in words, with its date."}},"type":"object","required":["address","reason","on","message"],"title":"RecipientRefusal","description":"An address of the conversation the brand no longer writes to."},"RecommendedPane":{"properties":{"who_wins":{"items":{"$ref":"#/components/schemas/StandingRow"},"type":"array","title":"Who Wins"},"prompts_total":{"type":"integer","title":"Prompts Total","description":"All prompts matching this selection before paging."}},"type":"object","required":["who_wins","prompts_total"],"title":"RecommendedPane","description":"What only Recommended's pane shows (BR-4): who wins the period's\nanswers, and the prompts a win is out of."},"RecordedReference":{"properties":{"source":{"type":"string","title":"Source","description":"The ref of the source this passage was checked against."},"quote":{"type":"string","title":"Quote","description":"The passage checked by the writer."},"verified":{"type":"boolean","title":"Verified","description":"Whether the source confirmed the passage."}},"type":"object","required":["source","quote","verified"],"title":"RecordedReference"},"RecordedSource":{"properties":{"kind":{"type":"string","title":"Kind","description":"The kind of material the writer recorded."},"ref":{"type":"string","title":"Ref","description":"The source reference used by this report's references."},"text":{"type":"string","title":"Text","description":"The source text retained by the writer."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The source URL, when available."},"subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subject","description":"The subject the source supports."},"support_kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Support Kind","description":"How the source supports the piece."},"observed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Observed At","description":"When the material was observed."},"revision":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revision","description":"The source revision, when recorded."},"unavailable_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unavailable Reason","description":"Why the material could not be read."},"internal":{"type":"boolean","title":"Internal","description":"Whether the material is internal to the brand.","default":false},"first_person":{"type":"boolean","title":"First Person","description":"Whether the brand may narrate it as its own.","default":false}},"type":"object","required":["kind","ref","text"],"title":"RecordedSource"},"RenderedMove":{"properties":{"play":{"type":"string","title":"Play","description":"The play the work is filed under."},"title":{"type":"string","title":"Title"},"rationale":{"type":"string","title":"Rationale","description":"The finding the work answers."},"effort":{"type":"string","enum":["low","medium","high"],"title":"Effort","description":"What is left for you once Heralded's deliverable is in hand."},"pointer_type":{"type":"string","title":"Pointer Type","description":"readiness_signal for a site check, url for a page, empty otherwise."},"pointer_target":{"type":"string","title":"Pointer Target","description":"The check or the page the work is on."},"grounds":{"$ref":"#/components/schemas/GroundsResponse"},"gain":{"$ref":"#/components/schemas/GainResponse"}},"type":"object","required":["play","title","rationale","effort","pointer_type","pointer_target","grounds","gain"],"title":"RenderedMove","description":"One piece of work a report suggests, as its play would file it."},"RepeatingPage":{"properties":{"url":{"type":"string","title":"Url","description":"The page's address, without tracking parameters."},"domain":{"type":"string","title":"Domain","description":"The page's registrable domain."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The page's title where it has one."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"The kind of page, such as a blog post or a review."},"citations":{"type":"integer","title":"Citations","description":"The period's answers that cited the page."},"owned":{"type":"boolean","title":"Owned","description":"Whether the page is on one of your own domains."},"state":{"anyOf":[{"type":"string","enum":["yours","new"]},{"type":"null"}],"title":"State","description":"`yours` for a page on your own domains, `new` for a page the newest report is the first to cite, otherwise null."}},"type":"object","required":["url","domain","title","type","citations","owned","state"],"title":"RepeatingPage","description":"A page AI cited that describes the brand with the label."},"ReportCompetitorEvidence":{"properties":{"brand_name":{"type":"string","title":"Brand Name","description":"A brand visible in this shared report."},"winning_questions":{"anyOf":[{"items":{"$ref":"#/components/schemas/RivalQuestion"},"type":"array"},{"type":"null"}],"title":"Winning Questions","description":"Unbranded questions naming this brand more often than you, most exclusive mentions first. Null if this brand's answer readings were not recorded."},"by_engine":{"anyOf":[{"items":{"$ref":"#/components/schemas/RivalEngine"},"type":"array"},{"type":"null"}],"title":"By Engine","description":"This brand's figures by engine. Null if its answer readings were not recorded."},"sources":{"anyOf":[{"items":{"$ref":"#/components/schemas/RivalSource"},"type":"array"},{"type":"null"}],"title":"Sources","description":"Read cited sites naming this brand, most citation occurrences first. Null if citation evidence was not recorded."}},"type":"object","required":["brand_name","winning_questions","by_engine","sources"],"title":"ReportCompetitorEvidence"},"ReportEditionRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The edition's id."},"scan_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Scan Id","description":"This weekly edition's full Snapshot; null when unavailable."},"brand_id":{"type":"string","format":"uuid","title":"Brand Id","description":"The brand row the edition measured."},"kind":{"type":"string","enum":["weekly","quarterly"],"title":"Kind","description":"weekly or quarterly."},"period_start":{"type":"string","format":"date-time","title":"Period Start","description":"Start of the period the edition covers."},"period_end":{"type":"string","format":"date-time","title":"Period End","description":"End of the period the edition covers."},"domain":{"type":"string","title":"Domain","description":"The brand's site when the edition issued."},"issued_at":{"type":"string","format":"date-time","title":"Issued At","description":"When the edition issued."},"pdf_ready":{"type":"boolean","title":"Pdf Ready","description":"Whether the PDF has rendered."},"shared_with":{"type":"integer","title":"Shared With","description":"People the edition has been sent to."},"body":{"$ref":"#/components/schemas/EditionBody","description":"The edition as it issued."}},"type":"object","required":["id","scan_id","brand_id","kind","period_start","period_end","domain","issued_at","pdf_ready","shared_with","body"],"title":"ReportEditionRead"},"ReportEditionRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The edition's id."},"scan_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Scan Id","description":"This weekly edition's full Snapshot; null when unavailable."},"brand_id":{"type":"string","format":"uuid","title":"Brand Id","description":"The brand row the edition measured."},"kind":{"type":"string","enum":["weekly","quarterly"],"title":"Kind","description":"weekly or quarterly."},"period_start":{"type":"string","format":"date-time","title":"Period Start","description":"Start of the period the edition covers."},"period_end":{"type":"string","format":"date-time","title":"Period End","description":"End of the period the edition covers."},"domain":{"type":"string","title":"Domain","description":"The brand's site when the edition issued."},"issued_at":{"type":"string","format":"date-time","title":"Issued At","description":"When the edition issued."},"pdf_ready":{"type":"boolean","title":"Pdf Ready","description":"Whether the PDF has rendered."},"shared_with":{"type":"integer","title":"Shared With","description":"People the edition has been sent to."}},"type":"object","required":["id","scan_id","brand_id","kind","period_start","period_end","domain","issued_at","pdf_ready","shared_with"],"title":"ReportEditionRow"},"ReportEditions":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"editions":{"items":{"$ref":"#/components/schemas/ReportEditionRow"},"type":"array","title":"Editions","description":"Newest period first."},"total":{"type":"integer","title":"Total","description":"Editions of this kind across the brand's sites."},"limit":{"type":"integer","title":"Limit","description":"The page size asked for."}},"type":"object","required":["meta","next_cursor","editions","total","limit"],"title":"ReportEditions","examples":[{"editions":[],"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"total":0}]},"ReportMarket":{"properties":{"status":{"type":"string","enum":["pending","complete","unavailable"],"title":"Status","description":"Pending, complete or unavailable market section."},"figures":{"anyOf":[{"$ref":"#/components/schemas/MarketFigures"},{"type":"null"}],"description":"The stored figures; null unless the section is complete."}},"type":"object","required":["status","figures"],"title":"ReportMarket","description":"A Snapshot's \"Your market\" section: `pending` until it lands, then its figures,\nor `unavailable` where it never did."},"ReportPositioningAxis":{"properties":{"axis":{"type":"string","title":"Axis"},"label":{"type":"string","title":"Label"},"engines":{"type":"integer","title":"Engines"},"diverges":{"type":"integer","title":"Diverges"},"pages":{"type":"integer","title":"Pages"},"flagged":{"type":"integer","title":"Flagged"},"unchecked":{"type":"integer","title":"Unchecked"},"flags":{"items":{"$ref":"#/components/schemas/ReportPositioningFlag"},"type":"array","title":"Flags"},"reads":{"items":{"$ref":"#/components/schemas/ReportPositioningRead"},"type":"array","title":"Reads","description":"One reading per engine, using the same verdicts as the aggregate counts."}},"type":"object","required":["axis","label","engines","diverges","pages","flagged","unchecked","flags","reads"],"title":"ReportPositioningAxis","description":"One frozen profile claim: its engine readings and divergence counts,\ncited-page coverage and the flagged pages the Understood pane lists."},"ReportPositioningFlag":{"properties":{"url":{"type":"string","title":"Url"},"domain":{"type":"string","title":"Domain"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"answers":{"type":"integer","title":"Answers"},"claim":{"type":"string","title":"Claim"},"passage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Passage"}},"type":"object","required":["url","domain","title","answers","claim","passage"],"title":"ReportPositioningFlag","description":"A page cited by answers that diverge on a claim, which the cited-page\npack flags as describing the brand differently on it (#3067)."},"ReportPositioningRead":{"properties":{"engine_id":{"type":"string","title":"Engine Id","description":"The engine that read this profile claim."},"verdict":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verdict","description":"The engine's verdict; null when not recorded."},"quote":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quote","description":"A representative passage; null when none was recorded."}},"type":"object","required":["engine_id","verdict","quote"],"title":"ReportPositioningRead"},"ReportQuery":{"properties":{"id":{"type":"string","title":"Id"},"query_text":{"type":"string","title":"Query Text"},"query_index":{"type":"integer","title":"Query Index"},"search_volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Volume"},"intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent"},"prompt_uid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Uid"},"asked_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asked Text"},"asked_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asked Language"}},"type":"object","required":["id","query_text","query_index","search_volume","intent","prompt_uid","asked_text","asked_language"],"title":"ReportQuery"},"ReportRun":{"properties":{"scan_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Scan Id","description":"The stable private scan reference, independent of the share URL."},"report_uuid":{"type":"string","format":"uuid","title":"Report Uuid"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"}},"type":"object","required":["scan_id","report_uuid","completed_at"],"title":"ReportRun","description":"An earlier run of a report, reachable on its own link."},"ReportScanResponse":{"properties":{"id":{"type":"string","title":"Id"},"report_uuid":{"type":"string","title":"Report Uuid"},"domain":{"type":"string","title":"Domain"},"domain_normalized":{"type":"string","title":"Domain Normalized"},"state":{"type":"string","enum":["pending_inference","awaiting_confirm","confirmed","running","unlocked","failed"],"title":"State"},"sells_to":{"type":"string","enum":["businesses","consumers"],"title":"Sells To","description":"Who the report measured the brand as selling to: `businesses` or `consumers`."},"ecommerce":{"type":"boolean","title":"Ecommerce","description":"Whether the report measured the brand as ecommerce."},"scan_tier":{"type":"string","const":"pro","title":"Scan Tier"},"score_version":{"type":"string","title":"Score Version"},"perception_score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Perception Score"},"detected_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detected Language"},"query_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query Language"},"weak_cell_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weak Cell Ratio"},"total_scored_cells":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Scored Cells"},"perception_sub_scores":{"additionalProperties":{"anyOf":[{"type":"integer"},{"type":"number"}]},"type":"object","title":"Perception Sub Scores"},"perception_sub_score_explanations":{"additionalProperties":true,"type":"object","title":"Perception Sub Score Explanations"},"axes":{"additionalProperties":true,"type":"object","title":"Axes"},"degradation_flags":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Degradation Flags"},"technical_readiness":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Technical Readiness"},"engine_calls_total":{"type":"integer","title":"Engine Calls Total","description":"Engine calls planned for this scan."},"queries":{"items":{"$ref":"#/components/schemas/ReportQuery"},"type":"array","title":"Queries"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"engine_market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Engine Market"},"engine_countries":{"anyOf":[{"items":{"$ref":"#/components/schemas/AskedCountry"},"type":"array"},{"type":"null"}],"title":"Engine Countries"},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url"},"icon_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon Url"},"pdf_storage_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pdf Storage Url"},"pdf_enqueued_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Pdf Enqueued At"},"pdf_generation_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pdf Generation Error"},"pdf_error_openings":{"items":{"type":"string"},"type":"array","title":"Pdf Error Openings"},"demand_coverage_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Demand Coverage Pct"},"site_blockers":{"anyOf":[{"$ref":"#/components/schemas/SiteBlockers"},{"type":"null"}]},"site_checks":{"anyOf":[{"$ref":"#/components/schemas/SiteChecks"},{"type":"null"}]},"heralded_score":{"anyOf":[{"$ref":"#/components/schemas/HeraldedScore"},{"type":"null"}]},"mentioned":{"anyOf":[{"$ref":"#/components/schemas/RankedRate"},{"type":"null"}]},"recommended":{"anyOf":[{"$ref":"#/components/schemas/RankedRate"},{"type":"null"}]},"describes_you":{"anyOf":[{"$ref":"#/components/schemas/DescribesYou"},{"type":"null"}]},"race":{"anyOf":[{"$ref":"#/components/schemas/Race"},{"type":"null"}]}},"type":"object","required":["id","report_uuid","domain","domain_normalized","state","sells_to","ecommerce","scan_tier","score_version","perception_score","detected_language","query_language","weak_cell_ratio","total_scored_cells","perception_sub_scores","perception_sub_score_explanations","axes","degradation_flags","technical_readiness","engine_calls_total","queries","completed_at","engine_market","engine_countries","logo_url","icon_url","pdf_storage_url","pdf_enqueued_at","pdf_generation_error","pdf_error_openings","demand_coverage_pct","site_blockers","site_checks","heralded_score","mentioned","recommended","describes_you","race"],"title":"ReportScanResponse","description":"The report's scan block. `axes`, the sub-score\nexplanations, `technical_readiness` and the degradation flags are frozen\nrun records served as stored, so they stay bare objects here."},"ReportShopping":{"properties":{"status":{"type":"string","enum":["pending","complete","unavailable"],"title":"Status","description":"Pending, complete or unavailable sections."},"products":{"anyOf":[{"$ref":"#/components/schemas/ShoppingProducts"},{"type":"null"}],"description":"\"Your products in AI shopping\"; null unless complete."},"readiness":{"anyOf":[{"$ref":"#/components/schemas/ShoppingReadiness"},{"type":"null"}],"description":"\"Ready for AI shopping\"; null unless complete."}},"type":"object","required":["status","products","readiness"],"title":"ReportShopping","description":"An ecommerce report's shopping sections: `pending` until they land, then\ntheir data, or `unavailable` where they never did."},"ResultEntry":{"properties":{"signal":{"anyOf":[{"type":"string","enum":["live","crawled","ranked","search_console","cited","moved"]},{"type":"string","const":"measured"}],"title":"Signal","description":"Signal this observation concerns."},"tone":{"type":"string","enum":["good","neutral","warning"],"title":"Tone","description":"Success, neutral watching, or warning for a failed read."},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary","description":"Observed result; null while pending."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Reason a signal could not be checked; null otherwise."},"at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"At","description":"Observation time, or measurement due date while pending."},"answer_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Answer Id","description":"Answer to open when this signal has recoverable answer evidence."},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name","description":"Engine display name when the signal concerns one engine."},"prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt","description":"Prompt text when the signal concerns an answer."},"citation":{"anyOf":[{"$ref":"#/components/schemas/FirstCitation"},{"type":"null"}],"description":"Qualifying citation evidence; null for other signals."},"state":{"anyOf":[{"type":"string","enum":["good","no_change","couldnt_check","pending"]},{"type":"string","const":"not_connected"}],"title":"State","description":"Success, unchanged or pending signal, failed read, or missing connection."}},"type":"object","required":["signal","tone","summary","reason","at","answer_id","display_name","prompt","citation","state"],"title":"ResultEntry"},"ResultRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The action or recurring job id."},"tracked_domain_id":{"type":"string","format":"uuid","title":"Tracked Domain Id","description":"Deprecated alias of brand_id.","deprecated":true},"target_entity":{"type":"string","title":"Target Entity","description":"The page, prompt, source or check the work targets."},"write_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Write Language","description":"The writing language code."},"write_language_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Write Language Source","description":"How the language was chosen."},"write_language_locked":{"type":"boolean","title":"Write Language Locked","description":"Whether writing has locked the language.","default":false},"target_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Type","description":"What the target names; null when unknown."},"issue_type":{"anyOf":[{"$ref":"#/components/schemas/IssueType"},{"type":"string","enum":["daily_read","deep_read","inventory_crawl","detection_sweep","search_sweep"]}],"title":"Issue Type","description":"The kind of action or recurring job."},"segment":{"type":"string","title":"Segment","description":"The work's configured segment label."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The act this work proposes or delivers."},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"The finding behind the work; null when absent."},"state":{"type":"string","enum":["new","accepted","in_progress","blocked","looks_resolved","done","verified_no_move","deferred","dismissed","withdrawn"],"title":"State","description":"The action's lifecycle state."},"group":{"type":"string","enum":["new","your_input","dispatched","scheduled","waiting","settled","withdrawn"],"title":"Group","description":"The current work group."},"holder":{"anyOf":[{"type":"string","enum":["you","heralded","waiting"]},{"type":"null"}],"title":"Holder","description":"Who holds the next step; null when nobody does."},"stage":{"type":"string","enum":["observe","decide","do","verify"],"title":"Stage","description":"The work's observe, decide, do or verify stage."},"demand":{"type":"string","title":"Demand","description":"What the work is doing or waiting for."},"member":{"anyOf":[{"type":"string","enum":["writer","publicist","engineer","analyst"]},{"type":"null"}],"title":"Member","description":"The responsible team member; null for setup and prompt replacements."},"waiting_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Waiting Since","description":"When the current ask began; null outside your_input."},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"The first time Heralded started this action. Null on dismissed work."},"delivered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Delivered At","description":"When the result went live, was sent or was published. Null on dismissed work."},"paid_off_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paid Off At","description":"When verification credited a positive measured gain. Null on dismissed work."},"preview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preview","description":"Up to 400 characters of draft opening, email recipient and subject, or planned change while waiting on you."},"outcome":{"anyOf":[{"type":"string","enum":["verified_up","no_move","not_measured","dismissed"]},{"type":"null"}],"title":"Outcome","description":"How settled work ended; null while pending."},"gate":{"anyOf":[{"type":"string","enum":["approval","review"]},{"type":"null"}],"title":"Gate","description":"The review or approval awaited; null otherwise."},"settled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Settled At","description":"When measurement or the decision settled."},"impact_scale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Impact Scale","description":"The measure this action aims to improve."},"expected_impact_pts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expected Impact Pts","description":"Always null: the expected gain is `gain`."},"verified_impact_pts":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Verified Impact Pts","description":"The measured gain credited to the action."},"prompt_movement":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Movement","description":"Whether other work shares the prompt's movement."},"blocked_owner":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blocked Owner","description":"Who the action waits on; null when not blocked."},"check_again_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Check Again On","description":"When to check blocked work again."},"scheduled_for":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Scheduled For","description":"The scheduled start date; null when unset."},"scheduled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Scheduled At","description":"The recurring job's next start."},"repeat":{"anyOf":[{"type":"string","enum":["daily","weekly","thrice_weekly"]},{"type":"null"}],"title":"Repeat","description":"The recurring job's schedule."},"progress":{"anyOf":[{"$ref":"#/components/schemas/WorkProgressResponse"},{"type":"null"}],"description":"The running job's progress."},"platform":{"type":"boolean","title":"Platform","description":"Whether this is Heralded's recurring work.","default":false},"run_state":{"anyOf":[{"type":"string","enum":["scheduled","running","done","skipped","failed","stopped"]},{"type":"null"}],"title":"Run State","description":"The recurring job's current run state."},"assignee":{"anyOf":[{"$ref":"#/components/schemas/AssigneeResponse"},{"type":"null"}],"description":"The person accountable for the work."},"intent_bucket":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent Bucket","description":"The targeted prompt intent; null when absent."},"looks_resolved_evidence":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Looks Resolved Evidence","description":"Evidence for a resolution awaiting confirmation."},"not_seen_since_run":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Not Seen Since Run","description":"The first report that stopped seeing the finding."},"placed_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Placed Position","description":"The member's place in the proposal order."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When the action was marked done."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When this work was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When this work last changed."},"primary_verb":{"anyOf":[{"type":"string","enum":["dispatch","take","done","defer","dismiss","confirm","reject","restore","block","unblock","reopen"]},{"type":"string","const":"review"},{"type":"null"}],"title":"Primary Verb","description":"The main offered action; null when none is offered."},"setup_link":{"anyOf":[{"$ref":"#/components/schemas/SetupLink"},{"type":"null"}],"description":"Where to complete this setup task."},"secondary_verbs":{"items":{"type":"string","enum":["dispatch","take","done","defer","dismiss","confirm","reject","restore","block","unblock","reopen"]},"type":"array","title":"Secondary Verbs","description":"Other offered actions, in menu order."},"return_group":{"anyOf":[{"type":"string","enum":["new","your_input","dispatched","scheduled","waiting","settled","withdrawn"]},{"type":"null"}],"title":"Return Group","description":"The work group a return action resumes."},"job":{"$ref":"#/components/schemas/JobResponse","description":"The work's steps and available controls."},"note":{"anyOf":[{"$ref":"#/components/schemas/TaskNote"},{"type":"null"}],"description":"Task explanation with a live job step."},"credit_cost":{"type":"integer","title":"Credit Cost","description":"Content credits needed to dispatch this work."},"credits_spent":{"type":"integer","title":"Credits Spent","description":"Content credits charged to this work and not refunded."},"dispatchable":{"type":"boolean","title":"Dispatchable","description":"Whether Heralded can execute this work."},"draft_in_flight":{"anyOf":[{"type":"string","enum":["drafting","redrafting"]},{"type":"null"}],"title":"Draft In Flight","description":"Whether a first draft or redraft is being written."},"grounds":{"anyOf":[{"$ref":"#/components/schemas/GroundsResponse"},{"type":"null"}],"description":"What the work rests on; null on Heralded's own work and on work filed before actions carried their grounds."},"done_when":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Done When","description":"When the work is done; null on Heralded's own work."},"tracking":{"items":{"type":"string","enum":["live","crawled","ranked","search_console","cited","moved"]},"type":"array","title":"Tracking","description":"What Heralded tracks once the work is live: live, crawled, ranked, search_console, cited, moved."},"first_citation":{"anyOf":[{"$ref":"#/components/schemas/FirstCitation"},{"type":"null"}],"description":"First qualifying citation of the delivered page."},"citation_count":{"type":"integer","title":"Citation Count","description":"Distinct engine and prompt citation pairs before the list cap.","default":0},"gain":{"anyOf":[{"$ref":"#/components/schemas/GainResponse"},{"type":"null"}],"description":"The expected gain: its band and what the work aims at. Null on Heralded's own work."},"focus":{"anyOf":[{"$ref":"#/components/schemas/FocusTag"},{"type":"null"}],"description":"The starred topic or competitor the work serves, or outside your focus. Null when the brand has no starred topic or competitor, and on Heralded's own work."},"kind_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind Tag","description":"A tag on the kind of work, shown beside its state, such as Sponsored. Null on work that has none."},"ending":{"anyOf":[{"$ref":"#/components/schemas/EndingResponse"},{"type":"null"}],"description":"How the task ended: its key, its words and when. Null while it is open."},"wait":{"anyOf":[{"$ref":"#/components/schemas/WaitResponse"},{"type":"null"}],"description":"What the task waits for, on whom and until when. Null while it waits on nobody."},"status_label":{"type":"string","enum":["Delivered","Cited","Paying off"],"title":"Status Label","description":"Paying off for verified gains, else Cited or Delivered."},"result_at":{"type":"string","format":"date-time","title":"Result At","description":"Latest delivery, citation or measured outcome date."},"measured":{"anyOf":[{"$ref":"#/components/schemas/ResultEntry"},{"type":"null"}],"description":"The measured outcome or pending result due date."},"results":{"$ref":"#/components/schemas/ActionResults","description":"This play's ordered steps and grouped observations."},"brand_id":{"type":"string","format":"uuid","title":"Brand Id","description":"The brand this work belongs to.","readOnly":true},"route":{"type":"string","enum":["home","actions","prompts","search","market","sources","content","perception","audit"],"title":"Route","description":"The Command Center page this work concerns.","readOnly":true}},"type":"object","required":["id","tracked_domain_id","target_entity","write_language","write_language_source","write_language_locked","target_type","issue_type","segment","title","detail","state","group","holder","stage","demand","member","waiting_since","started_at","delivered_at","paid_off_at","preview","outcome","gate","settled_at","impact_scale","expected_impact_pts","verified_impact_pts","prompt_movement","blocked_owner","check_again_on","scheduled_for","scheduled_at","repeat","progress","platform","run_state","assignee","intent_bucket","looks_resolved_evidence","not_seen_since_run","placed_position","completed_at","created_at","updated_at","primary_verb","setup_link","secondary_verbs","return_group","job","note","credit_cost","credits_spent","dispatchable","draft_in_flight","grounds","done_when","tracking","first_citation","citation_count","gain","focus","kind_tag","ending","wait","status_label","result_at","measured","results","brand_id","route"],"title":"ResultRow"},"ResultStep":{"properties":{"signal":{"anyOf":[{"type":"string","enum":["live","crawled","ranked","search_console","cited","moved"]},{"type":"string","const":"measured"}],"title":"Signal","description":"Signal this observation concerns."},"tone":{"type":"string","enum":["good","neutral","warning"],"title":"Tone","description":"Success, neutral watching, or warning for a failed read."},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary","description":"Observed result; null while pending."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Reason a signal could not be checked; null otherwise."},"at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"At","description":"Observation time, or measurement due date while pending."},"answer_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Answer Id","description":"Answer to open when this signal has recoverable answer evidence."},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name","description":"Engine display name when the signal concerns one engine."},"prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt","description":"Prompt text when the signal concerns an answer."},"citation":{"anyOf":[{"$ref":"#/components/schemas/FirstCitation"},{"type":"null"}],"description":"Qualifying citation evidence; null for other signals."},"label":{"type":"string","title":"Label","description":"Result step or measured outcome in customer-facing words."},"state":{"anyOf":[{"type":"string","enum":["good","no_change","couldnt_check","pending"]},{"type":"string","enum":["not_connected","no_effect","fell","inconclusive"]}],"title":"State","description":"Observed, pending, unchanged, unavailable, or measured outcome state."},"metric":{"anyOf":[{"type":"string","enum":["mentioned","recommended"]},{"type":"null"}],"title":"Metric","description":"Verified answer metric; null for observations and other outcomes."}},"type":"object","required":["signal","tone","summary","reason","at","answer_id","display_name","prompt","citation","label","state","metric"],"title":"ResultStep"},"ReviewProfileUrl":{"properties":{"platform":{"type":"string","title":"Platform"},"label":{"type":"string","title":"Label"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"}},"type":"object","required":["platform","label","url"],"title":"ReviewProfileUrl","description":"One review platform and the profile page the brand gave on it, if any."},"RivalAxes":{"properties":{"brand_key":{"type":"string","title":"Brand Key"},"brand_name":{"type":"string","title":"Brand Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"is_subject":{"type":"boolean","title":"Is Subject"},"axes":{"items":{"$ref":"#/components/schemas/PerceptionAxisFigure"},"type":"array","title":"Axes"},"heralded_score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Heralded Score"},"mentioned":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentioned"},"recommended":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Recommended"}},"type":"object","required":["brand_key","brand_name","domain","is_subject","axes","heralded_score","mentioned","recommended"],"title":"RivalAxes","description":"One brand on the rival block of every pane but Understood (#2358): the\nthree axes a rival can be read on, over the same answers the brand was\nread on, so a rival's 40% and the brand's 60% are shares of one\npopulation. Understood has no rival figure — there is no rival profile\nto match an answer against — so `axes` carries three, not four.\n\nSerialised once under `Perception.rivals` and read by every pane, the way\nthe prompt rows are; each pane picks its own axis off the row."},"RivalEngine":{"properties":{"engine_id":{"type":"string","title":"Engine Id","description":"The engine that answered."},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score","description":"This brand's Heralded Score on the engine; null if unmeasured."},"mentioned":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentioned","description":"The percentage of unbranded answers naming this brand; null if unmeasured."},"recommended":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Recommended","description":"The percentage of unbranded answers recommending this brand; null if unmeasured."}},"type":"object","required":["engine_id","score","mentioned","recommended"],"title":"RivalEngine"},"RivalPagePane":{"properties":{"question_trend":{"anyOf":[{"$ref":"#/components/schemas/MetricSeries"},{"type":"null"}],"description":"Weekly counts of distinct tracked questions citing this page under the selected filters; null without a preview read."},"questions_delta":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Questions Delta","description":"Change in distinct citing questions against the preceding comparable period; null with missing or incomparable citation coverage."},"answers_link":{"anyOf":[{"$ref":"#/components/schemas/AnswersLink"},{"type":"null"}]},"engine_vocabulary":{"items":{"$ref":"#/components/schemas/EngineVocabulary"},"type":"array","title":"Engine Vocabulary"},"window":{"anyOf":[{"$ref":"#/components/schemas/WindowDescriptor"},{"type":"null"}]},"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"brand_key":{"type":"string","title":"Brand Key"},"brand_name":{"type":"string","title":"Brand Name"},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type"},"headline":{"type":"string","title":"Headline"},"measurement":{"type":"string","title":"Measurement","description":"How the page was measured. New measurement values may be added within v1.","x-extensible-enum":["measured","daily_only","unavailable"]},"citation_evidence":{"type":"string","enum":["complete","partial","unavailable"],"title":"Citation Evidence","default":"complete"},"unavailable_scans":{"type":"integer","title":"Unavailable Scans","default":0},"prompt_count":{"type":"integer","title":"Prompt Count","description":"Prompts represented by this row under the selected filters."},"total_prompt_count":{"type":"integer","title":"Total Prompt Count","description":"All prompts for this competitor before paging."},"engine_ids":{"items":{"type":"string"},"type":"array","title":"Engine Ids"},"first_cited_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Cited At"},"why_it_works":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Why It Works"},"prompts":{"items":{"$ref":"#/components/schemas/PanePrompt"},"type":"array","title":"Prompts"},"prompts_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompts Limit","description":"Maximum citing questions returned in this page; null for the complete selection."},"prompts_offset":{"type":"integer","title":"Prompts Offset","description":"Citing questions skipped before this page.","default":0},"actions":{"items":{"$ref":"#/components/schemas/PaneAction"},"type":"array","title":"Actions"},"actions_total":{"type":"integer","title":"Actions Total","description":"Every live action about this subject, before the list is cut.","default":0},"next_step_action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Next Step Action Id","description":"The highest-priority live action that awaits a member and whose verb the reader may press; null when there is none."},"next_step":{"anyOf":[{"$ref":"#/components/schemas/PaneAction"},{"type":"null"}],"description":"The action `next_step_action_id` names, in the same shape as `actions`."}},"type":"object","required":["question_trend","questions_delta","answers_link","engine_vocabulary","window","url","title","brand_key","brand_name","content_type","headline","measurement","citation_evidence","unavailable_scans","prompt_count","total_prompt_count","engine_ids","first_cited_at","why_it_works","prompts","prompts_limit","prompts_offset","actions","actions_total","next_step_action_id","next_step"],"title":"RivalPagePane"},"RivalQuestion":{"properties":{"query_id":{"type":"string","format":"uuid","title":"Query Id"},"question":{"type":"string","title":"Question"},"competitor":{"type":"string","title":"Competitor"},"answers":{"type":"integer","title":"Answers","description":"Answers that named this competitor while leaving you unnamed."}},"type":"object","required":["query_id","question","competitor","answers"],"title":"RivalQuestion"},"RivalSource":{"properties":{"domain":{"type":"string","title":"Domain","description":"The cited site's domain."},"url":{"type":"string","title":"Url","description":"One read cited page on the site that names this brand."},"citation_count":{"type":"integer","title":"Citation Count","description":"Distinct answer/page citation occurrences from this site naming the brand."}},"type":"object","required":["domain","url","citation_count"],"title":"RivalSource"},"RivalTag":{"properties":{"brand_key":{"type":"string","title":"Brand Key"},"brand_name":{"type":"string","title":"Brand Name"},"status":{"type":"string","title":"Status"},"source":{"type":"string","title":"Source"}},"type":"object","required":["brand_key","brand_name","status","source"],"title":"RivalTag"},"RosterPool":{"properties":{"used":{"type":"integer","title":"Used"},"cap":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cap"}},"type":"object","required":["used","cap"],"title":"RosterPool","description":"Roster size as a pool (MK-4). `cap` is `None` on a workspace with no\nactive subscription to read one off."},"ScopeEntry":{"properties":{"host":{"type":"string","title":"Host"},"path_prefix":{"type":"string","title":"Path Prefix"},"state":{"type":"string","enum":["site","listed","ignored"],"title":"State"},"signals":{"additionalProperties":true,"type":"object","title":"Signals"},"decided_by":{"type":"string","enum":["rules","model","member"],"title":"Decided By"},"decided_at":{"type":"string","format":"date-time","title":"Decided At"},"pages":{"type":"integer","minimum":0.0,"title":"Pages","default":0}},"type":"object","required":["host","path_prefix","state","signals","decided_by","decided_at","pages"],"title":"ScopeEntry"},"ScoreBand":{"properties":{"label":{"type":"string","title":"Label"},"low":{"type":"integer","title":"Low"},"high":{"type":"integer","title":"High"}},"type":"object","required":["label","low","high"],"title":"ScoreBand","description":"One band of the Heralded Score: its word and the scores it spans."},"ScoreMark":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value"},"state":{"type":"string","title":"State","x-extensible-enum":["measured","too_few_answers","calibrating","first_report","not_comparable","not_measured","pending","not_scored"]},"band":{"type":"string","title":"Band"},"answers":{"type":"integer","title":"Answers"},"tooltip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tooltip"},"answer_read_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Answer Read Id"}},"type":"object","required":["key","label","value","state","band","answers","tooltip","answer_read_id"],"title":"ScoreMark","description":"A score or figure from the figures read, with the band it is coloured\nby (#4259).\n\n`key` is the engine or the figure measured. `band` is the Heralded Score's\nband for the value, so a mark and a score read on one scale, and\n\"Not measured\" where no value is served, which includes a group under the\nminimum of answers. On a score, `answers` counts every answer the period\nread under the filters, including those a figure's own denominator leaves\nout."},"SegmentTopics":{"properties":{"tracked":{"type":"integer","title":"Tracked","description":"Active topics the segment tracks."},"limit":{"type":"integer","title":"Limit","description":"Legacy presentation hint. Use organisation topic capacity for admission.","deprecated":true},"blocks":{"type":"integer","title":"Blocks","description":"Always zero; topic blocks belong to the organisation.","deprecated":true}},"type":"object","required":["tracked","limit","blocks"],"title":"SegmentTopics","description":"The topics a segment tracks against what it may hold."},"SenderChoiceAddress":{"properties":{"address":{"type":"string","title":"Address","description":"A verified sending address of this mailbox."},"kind":{"type":"string","enum":["mailbox","alias"],"title":"Kind","description":"Whether this is the mailbox address or a verified alias."}},"type":"object","required":["address","kind"],"title":"SenderChoiceAddress"},"SenderChoiceMailbox":{"properties":{"account_id":{"type":"string","format":"uuid","title":"Account Id","description":"The usable connection instance ID."},"address":{"type":"string","title":"Address","description":"The mailbox's own address."},"addresses":{"items":{"$ref":"#/components/schemas/SenderChoiceAddress"},"type":"array","title":"Addresses","description":"Verified Send as addresses available on this instance."}},"type":"object","required":["account_id","address","addresses"],"title":"SenderChoiceMailbox"},"SenderChoices":{"properties":{"yours":{"items":{"$ref":"#/components/schemas/SenderChoiceMailbox"},"type":"array","title":"Yours","description":"The viewer's usable personal mailboxes."},"shared":{"items":{"$ref":"#/components/schemas/SenderChoiceMailbox"},"type":"array","title":"Shared","description":"Shared mailboxes this viewer may use."},"own_mail":{"type":"boolean","title":"Own Mail","description":"Whether the viewer may choose to send through their own mail.","default":true}},"type":"object","required":["yours","shared","own_mail"],"title":"SenderChoices"},"SenderSuggestion":{"properties":{"account_id":{"type":"string","format":"uuid","title":"Account Id","description":"The suggested connection instance ID, without replacing a stored choice."},"address":{"type":"string","title":"Address","description":"The suggested instance's default From address."}},"type":"object","required":["account_id","address"],"title":"SenderSuggestion"},"SentimentQueryCell":{"properties":{"state":{"type":"string","enum":["strongly_negative","negative","neutral","positive","strongly_positive","not_mentioned","mixed"],"title":"State"},"score":{"anyOf":[{"type":"integer","enum":[-2,-1,0,1,2]},{"type":"null"}],"title":"Score"},"confidence":{"anyOf":[{"type":"string","enum":["high","medium","low"]},{"type":"null"}],"title":"Confidence"},"per_engine":{"items":{"$ref":"#/components/schemas/EnginePoint"},"type":"array","title":"Per Engine"}},"type":"object","required":["state","score","confidence","per_engine"],"title":"SentimentQueryCell"},"SentimentQueryRow":{"properties":{"query_id":{"type":"string","title":"Query Id"},"query_text":{"type":"string","title":"Query Text"},"cells":{"additionalProperties":{"$ref":"#/components/schemas/SentimentQueryCell"},"type":"object","title":"Cells"}},"type":"object","required":["query_id","query_text","cells"],"title":"SentimentQueryRow"},"SentimentSection":{"properties":{"status":{"type":"string","enum":["ready","unavailable"],"title":"Status"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"rows":{"items":{"$ref":"#/components/schemas/SentimentQueryRow"},"type":"array","maxItems":50,"title":"Rows"}},"additionalProperties":false,"type":"object","required":["status","message","rows"],"title":"SentimentSection"},"SeriesPoint":{"properties":{"run_number":{"type":"integer","title":"Run Number"},"completed_at":{"type":"string","title":"Completed At"},"value":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"null"}],"title":"Value"},"degraded":{"type":"boolean","title":"Degraded","default":false},"measured_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Measured Domain"},"key":{"anyOf":[{"$ref":"#/components/schemas/ComparabilityKey"},{"type":"null"}]},"breaks":{"items":{"$ref":"#/components/schemas/KeyChange"},"type":"array","title":"Breaks","default":[]},"prompts_changed":{"type":"boolean","title":"Prompts Changed","default":false},"break":{"anyOf":[{"$ref":"#/components/schemas/TrendBreak"},{"type":"null"}],"readOnly":true}},"type":"object","required":["run_number","completed_at","value","degraded","measured_domain","key","breaks","prompts_changed","break"],"title":"SeriesPoint"},"ServedInsight":{"properties":{"id":{"type":"string","title":"Id","description":"Stable across reads: `finding:<id>`, `check:<page>:<check>`, `page:<claim>:<url>`, `source:<domain>`, `rates:<domain>`, `opinion:<id>`, `topic:<topic>:<segment>`, `move:<competitor>:<change>:<week>:<url>`, `question:<prompt>` or `product:<product>`."},"kinds":{"items":{"$ref":"#/components/schemas/InsightKind"},"type":"array","title":"Kinds","description":"The kinds of work that fit it; empty when none does."},"work":{"anyOf":[{"$ref":"#/components/schemas/InsightWork"},{"type":"null"}],"description":"The work filed from it, which filing it again returns; null when none is."}},"type":"object","required":["id","kinds","work"],"title":"ServedInsight"},"ServiceAudit":{"properties":{"scan_id":{"type":"string","format":"uuid","title":"Scan Id"},"state":{"type":"string","enum":["preparing","running","completed","failed"],"title":"State"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When the audit completed; null until it completes."},"audit_progress":{"anyOf":[{"$ref":"#/components/schemas/AuditProgress"},{"type":"null"}]},"failure_reason":{"anyOf":[{"type":"string","enum":["stuck_no_progress","brief_abandoned","insufficient_engine_signal","cost_cap_exceeded","report_inputs_missing","service_unavailable","other"]},{"type":"null"}],"title":"Failure Reason"},"website":{"anyOf":[{"$ref":"#/components/schemas/V1Website"},{"type":"null"}]},"brief":{"anyOf":[{"$ref":"#/components/schemas/V1AuditBrief"},{"type":"null"}]},"collections":{"items":{"$ref":"#/components/schemas/ServiceCollection"},"type":"array","title":"Collections"},"stack":{"items":{"$ref":"#/components/schemas/StackTool"},"type":"array","title":"Stack","description":"Tools observed on the homepage, key pages or public DNS. No score impact."},"metrics":{"anyOf":[{"$ref":"#/components/schemas/ServiceMetrics"},{"type":"null"}],"description":"The audited page's raw figures; null until the audit completes."},"screenshots":{"anyOf":[{"$ref":"#/components/schemas/ServiceScreenshots"},{"type":"null"}],"description":"Full-page screenshots of the audited URL; null until the audit completes or when none could be taken."}},"type":"object","required":["scan_id","state","completed_at","audit_progress","failure_reason","website","brief","collections","stack","metrics","screenshots"],"title":"ServiceAudit"},"ServiceCollection":{"properties":{"key":{"type":"string","title":"Key"},"kind":{"type":"string","title":"Kind","default":"other"},"label":{"type":"string","title":"Label","default":""},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Count"},"sampled":{"type":"boolean","title":"Sampled","default":false},"read":{"type":"integer","title":"Read","default":0}},"type":"object","required":["key","kind","label","count","sampled","read"],"title":"ServiceCollection"},"ServiceKeyPage":{"properties":{"url":{"type":"string","title":"Url"},"path":{"type":"string","title":"Path","description":"Pass it, without its leading slash, to read this page alone."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"above_the_fold":{"$ref":"#/components/schemas/V1AboveTheFold"},"moves":{"items":{"$ref":"#/components/schemas/V1KeyPageChange"},"type":"array","title":"Moves","description":"What changed in the served read."},"strip":{"items":{"$ref":"#/components/schemas/V1KeyPageWeek"},"type":"array","title":"Strip","description":"The last four reads, oldest first."},"history":{"items":{"$ref":"#/components/schemas/V1KeyPageRead"},"type":"array","title":"History","description":"Its reads, newest first, up to 13."},"content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Hash"}},"type":"object","required":["url","path","title","above_the_fold","moves","strip","history","content_hash"],"title":"ServiceKeyPage"},"ServiceKeyPages":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"state":{"type":"string","enum":["complete","pending","unavailable"],"title":"State"},"summary":{"anyOf":[{"$ref":"#/components/schemas/V1KeyPagesSummary"},{"type":"null"}]},"key_pages":{"items":{"$ref":"#/components/schemas/ServiceKeyPage"},"type":"array","title":"Key Pages"}},"type":"object","required":["meta","next_cursor","total","limit","offset","state","summary","key_pages"],"title":"ServiceKeyPages","examples":[{"key_pages":[],"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"state":"complete","summary":null,"total":0}]},"ServiceMetrics":{"properties":{"lcp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Lcp Ms","description":"Largest Contentful Paint on a simulated mobile load, in milliseconds: the median of three lab runs. Null when PageSpeed did not measure the page."},"page_weight_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Weight Bytes","description":"Bytes the page transfers on that load; null when not measured."},"requests":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Requests","description":"Network requests the page makes on that load; null when not measured."},"performance_score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Performance Score","description":"The Lighthouse performance score, 0 to 100; null when not measured."},"pages_read":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages Read","description":"Pages the audit read; null when it froze no map."},"ai_readable_pages":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ai Readable Pages","description":"Of pages_read, those that load and that AI engines can read."},"trackers_before_consent":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Trackers Before Consent","description":"Different tracking tags (analytics, advertising, tag managers) loaded by pages with no consent tool."}},"type":"object","required":["lcp_ms","page_weight_bytes","requests","performance_score","pages_read","ai_readable_pages","trackers_before_consent"],"title":"ServiceMetrics","description":"The raw figures of the audited page, for a before and after comparison."},"ServicePage":{"properties":{"section":{"type":"string","title":"Section","description":"URL section, past a locale prefix.","default":"Site"},"finding_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Finding Ids","description":"Findings holding this page back; null where not measured."},"funnel":{"anyOf":[{"$ref":"#/components/schemas/PageFunnel"},{"type":"null"}],"description":"The page funnel on the pinned weekly window; null without a page id."},"path":{"type":"string","title":"Path"},"status_word":{"type":"string","title":"Status Word"},"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"page_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Page Id"},"page_type":{"type":"string","title":"Page Type"},"status":{"type":"string","enum":["readable","blocked_robots","noindex","does_not_load","needs_javascript","not_read"],"title":"Status"},"gates":{"items":{"$ref":"#/components/schemas/V1AuditGate"},"type":"array","title":"Gates"},"citations":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Citations","description":"Citations in the last weekly scan, citations_scan; null where that scan could not keep all its citations."},"crawler_hits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Crawler Hits","description":"Served crawler requests from the same frozen 28-day weekly scan window as page reads, ending two days before the scan started."},"read_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Read At"},"category":{"anyOf":[{"$ref":"#/components/schemas/AuditPageCategory"},{"type":"null"}],"description":"Where the page sits in the site's makeup, as the run categorised it."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"A code from facets.languages."},"findings":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Findings","description":"The findings holding the page back."},"worst":{"anyOf":[{"type":"string","enum":["issue","improve"]},{"type":"null"}],"title":"Worst","description":"The worst severity among them; null where there are none."},"claims_stated":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Claims Stated","description":"How many of claims_asked the page states; null where it was not asked."},"claims_asked":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Claims Asked","description":"The brief's claims (category, buyer, difference) asked of the page."},"change":{"anyOf":[{"type":"string","enum":["new","changed"]},{"type":"null"}],"title":"Change","description":"Found, or its content changed, since the previous weekly read."},"content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Hash"}},"type":"object","required":["section","finding_ids","funnel","path","status_word","url","title","page_id","page_type","status","gates","citations","crawler_hits","read_at","category","language","findings","worst","claims_stated","claims_asked","change","content_hash"],"title":"ServicePage"},"ServicePageText":{"properties":{"url":{"type":"string","title":"Url"},"content_hash":{"type":"string","title":"Content Hash"},"text":{"type":"string","title":"Text"}},"type":"object","required":["url","content_hash","text"],"title":"ServicePageText"},"ServicePages":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"state":{"type":"string","enum":["ready","awaiting_first_crawl","unavailable"],"title":"State"},"facets":{"$ref":"#/components/schemas/AuditFacets"},"crawler_hits_available":{"type":"boolean","title":"Crawler Hits Available"},"crawler_hits_days":{"type":"integer","title":"Crawler Hits Days"},"citations_scan":{"anyOf":[{"$ref":"#/components/schemas/DataAsOf"},{"type":"null"}]},"pages":{"items":{"$ref":"#/components/schemas/ServicePage"},"type":"array","title":"Pages"}},"type":"object","required":["meta","next_cursor","total","limit","offset","state","facets","crawler_hits_available","crawler_hits_days","citations_scan","pages"],"title":"ServicePages","examples":[{"citations_scan":null,"crawler_hits_available":false,"crawler_hits_days":0,"facets":{"categories":[],"languages":[]},"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"pages":[],"state":"ready","total":0}]},"ServiceScreenshot":{"properties":{"url":{"type":"string","title":"Url","description":"The image's address. Fetch it with the same service token; it stays available while the audit is kept, at least 30 days."},"width":{"type":"integer","title":"Width","description":"Pixels."},"height":{"type":"integer","title":"Height","description":"Pixels; a long page is cut at 8,000."}},"type":"object","required":["url","width","height"],"title":"ServiceScreenshot"},"ServiceScreenshots":{"properties":{"desktop":{"anyOf":[{"$ref":"#/components/schemas/ServiceScreenshot"},{"type":"null"}],"description":"Taken at 1440 pixels wide."},"phone":{"anyOf":[{"$ref":"#/components/schemas/ServiceScreenshot"},{"type":"null"}],"description":"Taken at 390 pixels wide."}},"type":"object","required":["desktop","phone"],"title":"ServiceScreenshots","description":"The audited URL's page whole, with JavaScript run and consent banners declined."},"SetupLink":{"properties":{"label":{"type":"string","title":"Label"},"href":{"type":"string","title":"Href"}},"type":"object","required":["label","href"],"title":"SetupLink"},"SharedProductRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The product's id."},"name":{"type":"string","title":"Name","description":"Your catalogue's title, else the name its cards showed."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The maker's own page for the product."},"yours":{"type":"boolean","title":"Yours","description":"The product is one of your brand's."},"maker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Maker","description":"A rival product's maker brand, where judged."},"shown":{"$ref":"#/components/schemas/ShoppingShare","description":"Answers showing this product divided by all answers with organic product cards, using the pooled answer ratio and interval."},"answers_shown":{"type":"integer","title":"Answers Shown","description":"Answers showing it in an organic card, on any topic."},"average_position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Position","description":"Its mean best organic place among the cards, when shown."},"best_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Position","description":"Its lowest organic card place across counted answers."},"seller_is_your_shop":{"anyOf":[{"$ref":"#/components/schemas/ShoppingShare"},{"type":"null"}],"description":"Its appearances naming your shop as the seller; null for a rival's."},"price_matches_your_shop":{"anyOf":[{"$ref":"#/components/schemas/ShoppingShare"},{"type":"null"}],"description":"Its appearances sold by your shop whose price matched; null for a rival's."},"offer":{"anyOf":[{"$ref":"#/components/schemas/ShoppingOffer"},{"type":"null"}],"description":"The newest card that showed it; null if none."},"maker_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Maker Key","description":"The canonical key of the product's maker: your own for your products, else the competitor's under `brand_keys`. Null where the maker is not known."}},"type":"object","required":["id","name","url","yours","maker","shown","answers_shown","average_position","best_position","seller_is_your_shop","price_matches_your_shop","offer","maker_key"],"title":"SharedProductRow","description":"A product of the brand or of a competitor the report shows, with its\nfigures in the scope that listed it."},"ShoppingAppearances":{"properties":{"yours":{"type":"integer","title":"Yours","description":"Answers showing at least one of your organic cards in version 2 sections. Version 1 sums individual product appearances."},"makers":{"items":{"$ref":"#/components/schemas/ShoppingMaker"},"type":"array","title":"Makers","description":"The makers of the products shown instead, most appearances first."}},"type":"object","required":["yours","makers"],"title":"ShoppingAppearances","description":"Who took the product cards, before the lists of products are capped."},"ShoppingCardFigures":{"properties":{"in_product_cards":{"$ref":"#/components/schemas/ShoppingShare","description":"Answers showing at least one of your products, divided by all answers with organic product cards. Independent of catalogue topic coverage; a pooled answer ratio."},"answers_with_cards":{"$ref":"#/components/schemas/ShoppingShare","description":"Answers whose cards were read that showed at least one organic product card."},"seller_is_your_shop":{"$ref":"#/components/schemas/ShoppingShare","description":"Your products' appearances with a seller shown that named your own shop."},"price_matches_your_shop":{"$ref":"#/components/schemas/ShoppingShare","description":"Appearances sold by your shop, of a variant matched to yours, whose price shown matched your shop's."},"average_position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Position","description":"The mean of each answer's best own organic place, among answers showing yours."},"positions":{"type":"integer","title":"Positions","description":"The answers the average position is the mean of."},"best_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Position","description":"Your lowest organic card place across counted answers."},"sponsored_only_answers":{"type":"integer","title":"Sponsored Only Answers","description":"Answers showing only sponsored cards, counted apart from every share."},"sponsored":{"items":{"$ref":"#/components/schemas/ShoppingSponsor"},"type":"array","title":"Sponsored","description":"Sponsored cards per advertiser, most answers first."},"engines":{"items":{"$ref":"#/components/schemas/ShoppingEngine"},"type":"array","title":"Engines","description":"How each engine's answers read for cards."}},"type":"object","required":["in_product_cards","answers_with_cards","seller_is_your_shop","price_matches_your_shop","average_position","positions","best_position","sponsored_only_answers","sponsored","engines"],"title":"ShoppingCardFigures","description":"The product card figures of a population of answers, each over its own\ndenominator."},"ShoppingCatalogue":{"properties":{"state":{"type":"string","enum":["complete","partial","unavailable"],"title":"State","description":"Whether the shop's catalogue was read whole, partly or not at all."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why a partial or unavailable read stopped."},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform","description":"The shop platform the read found."},"read_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Read At","description":"When the catalogue was read."},"products_read":{"type":"integer","title":"Products Read","description":"Products the read listed."},"complete_product_data":{"$ref":"#/components/schemas/ShoppingCount","description":"Checked products whose page states every required field."},"stages":{"items":{"$ref":"#/components/schemas/ShoppingStage"},"type":"array","title":"Stages","description":"The four readiness stages, in order."},"checks":{"items":{"$ref":"#/components/schemas/ShoppingCheck"},"type":"array","title":"Checks","description":"Every check, as the standards list them."},"fix_first":{"items":{"$ref":"#/components/schemas/ShoppingCheck"},"type":"array","title":"Fix First","description":"The failing checks, site access first, then required, then recommended, most failing first."}},"type":"object","required":["state","reason","platform","read_at","products_read","complete_product_data","stages","checks","fix_first"],"title":"ShoppingCatalogue","description":"The report's readiness: the read, its stages, its checks and what to\nfix first."},"ShoppingCatalogueRead":{"properties":{"state":{"type":"string","enum":["complete","partial","unavailable"],"title":"State","description":"Whether the shop's catalogue was read whole, partly or not at all."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why a partial or unavailable read stopped."},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform","description":"The shop platform the read found."},"read_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Read At","description":"When the catalogue was read."},"products_read":{"type":"integer","title":"Products Read","description":"Products the read listed."},"complete_product_data":{"$ref":"#/components/schemas/ShoppingCount","description":"Checked products whose page states every required field."}},"type":"object","required":["state","reason","platform","read_at","products_read","complete_product_data"],"title":"ShoppingCatalogueRead","description":"A catalogue read: how far it got, and its complete product data."},"ShoppingCheck":{"properties":{"id":{"type":"string","title":"Id","description":"The check."},"level":{"type":"string","enum":["required","recommended","access"],"title":"Level","description":"Required or recommended by the standards, or site access for a crawler."},"standards":{"items":{"type":"string"},"type":"array","title":"Standards","description":"Whose standard asks for it: google, openai."},"unit":{"type":"string","enum":["products","variants"],"title":"Unit","description":"What it counts: products, or variants for product codes."},"met":{"type":"integer","title":"Met","description":"Products or variants passing."},"checked":{"type":"integer","title":"Checked","description":"Products or variants it applied to and could run on."}},"type":"object","required":["id","level","standards","unit","met","checked"],"title":"ShoppingCheck"},"ShoppingCount":{"properties":{"met":{"type":"integer","title":"Met","description":"Checked products with every field Google and OpenAI require."},"checked":{"type":"integer","title":"Checked","description":"Products whose page was checked."}},"type":"object","required":["met","checked"],"title":"ShoppingCount"},"ShoppingEngine":{"properties":{"engine":{"type":"string","title":"Engine","description":"The answering engine."},"answers_read":{"type":"integer","title":"Answers Read","description":"Answers whose product cards were read."},"answers_with_cards":{"type":"integer","title":"Answers With Cards","description":"Of those, answers showing an organic card."},"answers_not_read":{"type":"integer","title":"Answers Not Read","description":"Answers on an engine whose product cards are not captured: text only, never a zero."},"answers_failed":{"type":"integer","title":"Answers Failed","description":"Answers whose product-card capture failed.","default":0}},"type":"object","required":["engine","answers_read","answers_with_cards","answers_not_read","answers_failed"],"title":"ShoppingEngine"},"ShoppingGoogle":{"properties":{"state":{"type":"string","enum":["complete","partial","unavailable","not_read"],"title":"State","description":"Whether every search's page was read, some, none, or no search was asked."},"searches":{"items":{"$ref":"#/components/schemas/ShoppingSearch"},"type":"array","title":"Searches","description":"Each Google Shopping search read."}},"type":"object","required":["state","searches"],"title":"ShoppingGoogle"},"ShoppingInstead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The product shown instead."},"name":{"type":"string","title":"Name","description":"Its name as its cards showed it."},"maker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Maker","description":"Its maker brand, where judged."},"answers_shown":{"type":"integer","title":"Answers Shown","description":"Answers showing it: in a question's list, the answers to that question; else the answers in the same filtered population."}},"type":"object","required":["id","name","maker","answers_shown"],"title":"ShoppingInstead"},"ShoppingMaker":{"properties":{"maker":{"type":"string","title":"Maker","description":"A maker brand of products shown instead, as judged."},"appearances":{"type":"integer","title":"Appearances","description":"Answers showing at least one organic card from this maker, counted once per answer in version 2 sections. Version 1 sums individual product appearances."}},"type":"object","required":["maker","appearances"],"title":"ShoppingMaker"},"ShoppingOffer":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The card's title."},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","description":"The card's image."},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price","description":"The price shown, or the bottom of a range."},"price_max":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price Max","description":"The top of a price range shown."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"The price's ISO 4217 currency."},"price_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price Text","description":"The price as the card displayed it."},"seller":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Seller","description":"The seller as the card displayed it."},"seller_is_your_shop":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Seller Is Your Shop","description":"The seller shown is your own shop; null with no seller."},"marketplace":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Marketplace","description":"The marketplace the card named."},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating","description":"The rating shown."},"rating_max":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating Max","description":"The rating's scale."},"rating_votes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rating Votes","description":"The ratings the rating counts."},"price_comparison":{"anyOf":[{"type":"string","enum":["matches","differs"]},{"type":"null"}],"title":"Price Comparison","description":"Against your shop's known price for the same variant and currency: matches or differs; null when comparison is unavailable."},"your_shop_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Your Shop Price","description":"Your shop's price for the variant shown."},"your_shop_currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Your Shop Currency","description":"Your shop's price currency."},"card_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Url","description":"Where the card links."},"merchant_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Merchant Url","description":"The merchant page the card links to."},"engine":{"type":"string","title":"Engine","description":"The engine whose answer showed the card."}},"type":"object","required":["title","image_url","price","price_max","currency","price_text","seller","seller_is_your_shop","marketplace","rating","rating_max","rating_votes","price_comparison","your_shop_price","your_shop_currency","card_url","merchant_url","engine"],"title":"ShoppingOffer","description":"A product as one card showed it: the newest best organic card of it."},"ShoppingProduct":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The product's id."},"name":{"type":"string","title":"Name","description":"Your catalogue's title, else the name its cards showed."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The maker's own page for the product."},"yours":{"type":"boolean","title":"Yours","description":"The product is one of your brand's."},"maker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Maker","description":"A rival product's maker brand, where judged."},"shown":{"$ref":"#/components/schemas/ShoppingShare","description":"Answers showing this product divided by all answers with organic product cards, using the pooled answer ratio and interval."},"answers_shown":{"type":"integer","title":"Answers Shown","description":"Answers showing it in an organic card, on any topic."},"average_position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Position","description":"Its mean best organic place among the cards, when shown."},"best_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Position","description":"Its lowest organic card place across counted answers."},"seller_is_your_shop":{"anyOf":[{"$ref":"#/components/schemas/ShoppingShare"},{"type":"null"}],"description":"Its appearances naming your shop as the seller; null for a rival's."},"price_matches_your_shop":{"anyOf":[{"$ref":"#/components/schemas/ShoppingShare"},{"type":"null"}],"description":"Its appearances sold by your shop whose price matched; null for a rival's."},"offer":{"anyOf":[{"$ref":"#/components/schemas/ShoppingOffer"},{"type":"null"}],"description":"The newest card that showed it; null if none."},"engines":{"items":{"$ref":"#/components/schemas/ShoppingProductEngine"},"type":"array","title":"Engines","description":"Its figures by engine."},"questions":{"items":{"$ref":"#/components/schemas/ShoppingQuestion"},"type":"array","title":"Questions","description":"The questions it was shown on, and for your products those on its topics where it was missed, most shown first."},"questions_total":{"type":"integer","title":"Questions Total","description":"All its questions before `questions` was capped."},"shown_instead":{"items":{"$ref":"#/components/schemas/ShoppingInstead"},"type":"array","title":"Shown Instead","description":"Products shown in the same filtered answers, most shown first; empty for a product that is not yours."}},"type":"object","required":["id","name","url","yours","maker","shown","answers_shown","average_position","best_position","seller_is_your_shop","price_matches_your_shop","offer","engines","questions","questions_total","shown_instead"],"title":"ShoppingProduct","description":"A product as the report's section and its panel show it."},"ShoppingProductEngine":{"properties":{"engine":{"type":"string","title":"Engine","description":"The answering engine."},"shown":{"$ref":"#/components/schemas/ShoppingShare","description":"The product's Shown share on that engine."},"answers_shown":{"type":"integer","title":"Answers Shown","description":"Answers on that engine showing it."},"average_position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Position","description":"Its average position on that engine."},"best_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Position","description":"Its lowest organic place on that engine."}},"type":"object","required":["engine","shown","answers_shown","average_position","best_position"],"title":"ShoppingProductEngine"},"ShoppingProducts":{"properties":{"version":{"type":"integer","title":"Version","description":"The stored claim's schema version."},"missing":{"items":{"type":"string","enum":["catalogue","coverage"]},"type":"array","title":"Missing","description":"Inputs the run could not read in full: the catalogue, and which of your products each topic covers for missed-question alerts. Card shares remain measured."},"figures":{"anyOf":[{"$ref":"#/components/schemas/ShoppingCardFigures"},{"type":"null"}],"description":"Product card figures; null where the run read no product cards."},"products":{"items":{"$ref":"#/components/schemas/ShoppingProduct"},"type":"array","title":"Products","description":"Your products shown in the cards, most shown first."},"products_total":{"type":"integer","title":"Products Total","description":"All your products shown, before the cap."},"shown_instead":{"items":{"$ref":"#/components/schemas/ShoppingProduct"},"type":"array","title":"Shown Instead","description":"Other brands' products shown in the cards, most shown first."},"shown_instead_total":{"type":"integer","title":"Shown Instead Total","description":"All of them, before the cap."},"questions":{"items":{"$ref":"#/components/schemas/ProductCardQuestion"},"type":"array","title":"Questions","description":"Unbranded questions and their product-card read states."},"brands":{"additionalProperties":{"$ref":"#/components/schemas/BrandProductCards"},"type":"object","title":"Brands","description":"Product-card answer shares and positions by maker key."},"strip":{"anyOf":[{"$ref":"#/components/schemas/ProductCardStrip"},{"type":"null"}],"description":"Counts of questions by their product-card read state."},"engines":{"items":{"$ref":"#/components/schemas/ProductCardEngine"},"type":"array","title":"Engines","description":"Questions with yours and with organic cards by engine."},"brand_keys":{"additionalProperties":{"type":"string"},"type":"object","title":"Brand Keys","description":"The canonical key of each brand the report names, by the name it shows: yours and the named competitors. The key indexes `brands` and filters the shared report's products read, so a reader never normalizes a name itself."},"more_brands":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"More Brands","description":"Makers beyond you and the Snapshot's named competitors, counted before capping."},"appearances":{"anyOf":[{"$ref":"#/components/schemas/ShoppingAppearances"},{"type":"null"}],"description":"Appearances in organic cards, yours and by maker, over every product shown; null on sections written before they were counted."}},"type":"object","required":["version","missing","figures","products","products_total","shown_instead","shown_instead_total","questions","brands","strip","engines","brand_keys","more_brands","appearances"],"title":"ShoppingProducts","description":"\"Your products in AI shopping\", as its `shopping` claim stores it."},"ShoppingQuestion":{"properties":{"id":{"type":"string","title":"Id","description":"The question's prompt id, or its query id."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text","description":"The question as asked."},"state":{"type":"string","enum":["shown","missed"],"title":"State","description":"shown: the product appeared; missed: products shown instead appeared on a topic covering it, and it did not."},"shown":{"$ref":"#/components/schemas/ShoppingShare","description":"Its Shown share on this question."},"answers_shown":{"type":"integer","title":"Answers Shown","description":"Answers to it showing the product."},"average_position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Position","description":"Its mean best organic place on this question, when shown."},"engines":{"items":{"$ref":"#/components/schemas/ShoppingQuestionEngine"},"type":"array","title":"Engines","description":"The engines that showed it."},"shown_instead":{"items":{"$ref":"#/components/schemas/ShoppingInstead"},"type":"array","title":"Shown Instead","description":"Rival products shown on this question where it was covered, most shown first."}},"type":"object","required":["id","text","state","shown","answers_shown","average_position","engines","shown_instead"],"title":"ShoppingQuestion"},"ShoppingQuestionEngine":{"properties":{"engine":{"type":"string","title":"Engine","description":"The engine that showed the product."},"position":{"type":"integer","title":"Position","description":"Its best organic place in that engine's cards."},"seller":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Seller","description":"The seller that card named."},"seller_is_your_shop":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Seller Is Your Shop","description":"That card's frozen seller ownership: true for your shop, false for another seller; null when unclassified or absent from an older saved report."},"answers":{"type":"integer","title":"Answers","description":"Answers on that engine showing it."}},"type":"object","required":["engine","position","seller","seller_is_your_shop","answers"],"title":"ShoppingQuestionEngine"},"ShoppingReadiness":{"properties":{"version":{"type":"integer","title":"Version","description":"The stored claim's schema version."},"catalogue":{"$ref":"#/components/schemas/ShoppingCatalogue","description":"The checked product pages against Google's and OpenAI's standards."},"google_shopping":{"$ref":"#/components/schemas/ShoppingGoogle","description":"Google Shopping placement."}},"type":"object","required":["version","catalogue","google_shopping"],"title":"ShoppingReadiness","description":"\"Ready for AI shopping\", as its `shopping_readiness` claim stores it."},"ShoppingSearch":{"properties":{"query":{"type":"string","title":"Query","description":"The words searched on Google Shopping."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"The search's country where its report holds it."},"location_code":{"type":"integer","title":"Location Code","description":"Google's location the search was read in."},"language":{"type":"string","title":"Language","description":"The search's language."},"volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Volume","description":"Monthly searches, where the report holds them."},"status":{"type":"string","enum":["succeeded","failed"],"title":"Status","description":"Whether the page was read."},"depth":{"type":"integer","title":"Depth","description":"How many organic products deep the page was read."},"yours":{"anyOf":[{"$ref":"#/components/schemas/ShoppingSearchLine"},{"type":"null"}],"description":"Your best product; null when none was in the products read, or on a failed read."},"in_results":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"In Results","description":"Whether one of your products was within `depth`; null on a failed read."},"leader":{"anyOf":[{"$ref":"#/components/schemas/ShoppingSearchLine"},{"type":"null"}],"description":"The page's first organic product."}},"type":"object","required":["query","country","location_code","language","volume","status","depth","yours","in_results","leader"],"title":"ShoppingSearch"},"ShoppingSearchLine":{"properties":{"position":{"type":"integer","title":"Position","description":"Its place among the page's organic products, from 1."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The product as the page listed it."},"seller":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Seller","description":"The seller the page named."},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price","description":"The price listed."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"The price's ISO 4217 currency."},"product_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Product Id","description":"The product it resolved to, if any."}},"type":"object","required":["position","title","seller","price","currency","product_id"],"title":"ShoppingSearchLine"},"ShoppingShare":{"properties":{"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value","description":"The share in [0, 1]; null with no denominator."},"low":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Low","description":"The 95% range's low end; null with no denominator."},"high":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"High","description":"The 95% range's high end; null with no denominator."},"numerator":{"type":"integer","title":"Numerator","description":"The figure's own count."},"denominator":{"type":"integer","title":"Denominator","description":"The count it is a share of."}},"type":"object","required":["value","low","high","numerator","denominator"],"title":"ShoppingShare","description":"A share of answers over its own denominator, with its 95% range."},"ShoppingSponsor":{"properties":{"advertiser":{"type":"string","title":"Advertiser","description":"The advertiser as its first sponsored card showed it."},"answers":{"type":"integer","title":"Answers","description":"Answers showing a sponsored card of the advertiser."},"yours":{"type":"boolean","title":"Yours","description":"The advertiser is your brand."}},"type":"object","required":["advertiser","answers","yours"],"title":"ShoppingSponsor"},"ShoppingStage":{"properties":{"stage":{"type":"string","enum":["reach","understand","trust","identify"],"title":"Stage","description":"reach: crawlers may read the page; understand: required fields; trust: ratings, shipping and returns; identify: product codes."},"met":{"type":"integer","title":"Met","description":"Checked products passing every check of the stage that ran."},"checked":{"type":"integer","title":"Checked","description":"Checked products any check of the stage ran on."}},"type":"object","required":["stage","met","checked"],"title":"ShoppingStage"},"SideStanding":{"properties":{"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score"}},"type":"object","required":["rank","score"],"title":"SideStanding"},"SiteBlockers":{"properties":{"pages_checked":{"type":"integer","title":"Pages Checked"},"pages_blocked":{"type":"integer","title":"Pages Blocked"},"pages_unmeasured":{"type":"integer","title":"Pages Unmeasured"},"summary":{"type":"string","title":"Summary"},"blockers":{"items":{"$ref":"#/components/schemas/Blocker"},"type":"array","title":"Blockers"},"unmeasured":{"items":{"$ref":"#/components/schemas/UnmeasuredPage"},"type":"array","title":"Unmeasured"},"homepage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Homepage"},"gates":{"items":{"$ref":"#/components/schemas/ReadabilityCheck"},"type":"array","title":"Gates"}},"type":"object","required":["pages_checked","pages_blocked","pages_unmeasured","summary","blockers","unmeasured","homepage","gates"],"title":"SiteBlockers","description":"The blocker list: the site-wide robots.txt row first, then one row per\npage and blocker, then the pages we could not read."},"SiteChecks":{"properties":{"checks":{"items":{"$ref":"#/components/schemas/ReadabilityCheck"},"type":"array","title":"Checks"},"also_checked":{"items":{"$ref":"#/components/schemas/ReadabilityCheck"},"type":"array","title":"Also Checked"}},"type":"object","required":["checks","also_checked"],"title":"SiteChecks","description":"The homepage checks \"Can AI read your site?\" lists: the Site Health\nchecks a read files moves on, then `ALSO_CHECKED`."},"SiteKitResponse":{"properties":{"body":{"type":"string","title":"Body","description":"The fix kit text."},"placement":{"type":"string","title":"Placement","description":"Where the member puts the kit."},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename","description":"The download filename, null for a pasted snippet."}},"type":"object","required":["body","placement","filename"],"title":"SiteKitResponse"},"SnapshotProfileEdit":{"properties":{"brand_name":{"anyOf":[{"type":"string","maxLength":120,"minLength":1},{"type":"null"}],"title":"Brand Name","description":"The brand's name."},"description":{"anyOf":[{"type":"string","maxLength":400,"minLength":1},{"type":"null"}],"title":"Description","description":"What the brand does, in a sentence."},"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market","description":"Where AI engines are asked: global, europe or a country code such as GB."}},"additionalProperties":false,"type":"object","title":"SnapshotProfileEdit"},"SnapshotStart":{"properties":{"domain":{"type":"string","maxLength":253,"minLength":1,"title":"Domain","description":"The website to measure, such as acme.com."}},"additionalProperties":false,"type":"object","required":["domain"],"title":"SnapshotStart"},"SocialRead":{"properties":{"state":{"type":"string","title":"State","description":"The social image's state, pending until its first card settles."},"source":{"type":"string","enum":["card","image_only","featured","branded"],"title":"Source","description":"Sharing source: card by default, or image_only for the plain featured image."},"style":{"type":"string","enum":["mounted","strip","band"],"title":"Style","description":"Effective branded-card style, from the piece override or brand default."},"style_override":{"anyOf":[{"type":"string","enum":["mounted","strip","band"]},{"type":"null"}],"title":"Style Override","description":"The member's per-piece style, or null to follow the brand default."},"image":{"anyOf":[{"$ref":"#/components/schemas/ImageFile"},{"type":"null"}],"description":"The social image currently available to download."},"failure_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failure Code","description":"The branded render's machine-readable failure reason."},"failure_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failure Reason","description":"The branded render's refusal or failure explanation."}},"type":"object","required":["state","source","style","style_override","image","failure_code","failure_reason"],"title":"SocialRead"},"SourceBrandsRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"rows":{"items":{"$ref":"#/components/schemas/BrandFacts"},"type":"array","title":"Rows"}},"type":"object","required":["meta","next_cursor","total","limit","offset","rows"],"title":"SourceBrandsRead"},"SourceDetail":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"path":{"type":"string","title":"Path"},"domain":{"type":"string","title":"Domain"},"placements":{"$ref":"#/components/schemas/SourcePlacementsRead"},"mentions":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Mentions"},"recommends":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Recommends"},"pages":{"$ref":"#/components/schemas/SourcePagesRead"},"engines":{"$ref":"#/components/schemas/SourceEnginesRead"},"brands":{"$ref":"#/components/schemas/SourceBrandsRead"}},"type":"object","required":["meta","path","domain","placements","mentions","recommends","pages","engines","brands"],"title":"SourceDetail"},"SourceDomainCite":{"properties":{"domain":{"type":"string","maxLength":255,"minLength":1,"title":"Domain"},"cite_count":{"type":"integer","minimum":1.0,"title":"Cite Count","description":"Citations represented by this source or tier."}},"type":"object","required":["domain","cite_count"],"title":"SourceDomainCite"},"SourceEnginesRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"rows":{"items":{"type":"string"},"type":"array","title":"Rows"}},"type":"object","required":["meta","next_cursor","total","limit","offset","rows"],"title":"SourceEnginesRead"},"SourceMedals":{"properties":{"rank":{"type":"integer","title":"Rank"},"domain":{"type":"string","title":"Domain"},"answers":{"type":"integer","title":"Answers"},"citations":{"type":"integer","title":"Citations"},"boards":{"type":"integer","title":"Boards"},"medals":{"$ref":"#/components/schemas/Medals"},"first_places":{"items":{"$ref":"#/components/schemas/FirstPlace"},"type":"array","title":"First Places"},"europe_first_places":{"items":{"$ref":"#/components/schemas/FirstPlace"},"type":"array","title":"Europe First Places"}},"type":"object","required":["rank","domain","answers","citations","boards","medals","first_places","europe_first_places"],"title":"SourceMedals"},"SourceMixSegment":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"citations":{"type":"integer","title":"Citations"},"share_pct":{"type":"integer","title":"Share Pct"},"owner":{"type":"string","enum":["third_party","competitor","yours"],"title":"Owner"}},"type":"object","required":["key","label","citations","share_pct","owner"],"title":"SourceMixSegment"},"SourcePage":{"properties":{"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind"},"citations":{"type":"integer","title":"Citations"},"mentions":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Mentions"},"recommends":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Recommends"}},"type":"object","required":["url","title","kind","citations","mentions","recommends"],"title":"SourcePage"},"SourcePageName":{"properties":{"brand_key":{"type":"string","title":"Brand Key"},"name":{"type":"string","title":"Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"is_you":{"type":"boolean","title":"Is You"},"recommends":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Recommends"}},"type":"object","required":["brand_key","name","domain","is_you","recommends"],"title":"SourcePageName"},"SourcePagesRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"withheld":{"items":{"type":"integer"},"type":"array","title":"Withheld","description":"Ranks present in the module whose rows are withheld."},"rows":{"items":{"$ref":"#/components/schemas/SourcePage"},"type":"array","title":"Rows"}},"type":"object","required":["meta","next_cursor","total","limit","offset","withheld","rows"],"title":"SourcePagesRead"},"SourcePlacement":{"properties":{"filters":{"$ref":"#/components/schemas/LeaderboardFilters"},"path":{"type":"string","title":"Path"},"rank":{"type":"integer","title":"Rank"},"citations":{"type":"integer","title":"Citations"},"share_of_answers":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Share Of Answers","description":"Percentage of the board's answers citing this source, 0 to 100."}},"type":"object","required":["filters","path","rank","citations","share_of_answers"],"title":"SourcePlacement"},"SourcePlacements":{"properties":{"offers":{"items":{"type":"string","enum":["sponsored_article","review","list_placement","newsletter","affiliate_listing"]},"type":"array","title":"Offers","description":"What it sells: `sponsored_article`, `review`, `list_placement`, `newsletter` or `affiliate_listing` (a place paid by commission). Empty where the evidence says it sells without saying what."},"known_from":{"type":"string","enum":["commercial_page","sponsored_label"],"title":"Known From","description":"`commercial_page`: its advertise or media-kit page. `sponsored_label`: a sponsored label on its pages AI cites."},"page":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page","description":"Its commercial page, where one was read."},"price":{"anyOf":[{"$ref":"#/components/schemas/PublishedPrice"},{"type":"null"}],"description":"The price its commercial page publishes for one placement; null where it publishes none."},"estimate":{"anyOf":[{"$ref":"#/components/schemas/PriceEstimate"},{"type":"null"}],"description":"Where it publishes no price, an estimate for one article or list placement on a site of its authority, in EUR; null beside a published price or where its authority is unmeasured."},"read_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Read At","description":"When the site was read for what it sells."}},"type":"object","required":["offers","known_from","page","price","estimate","read_at"],"title":"SourcePlacements","description":"What a site sells, as a source read serves it."},"SourcePlacementsRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"rows":{"items":{"$ref":"#/components/schemas/SourcePlacement"},"type":"array","title":"Rows"}},"type":"object","required":["meta","next_cursor","total","limit","offset","rows"],"title":"SourcePlacementsRead"},"SourceRecommending":{"properties":{"count":{"type":"integer","title":"Count","description":"Third-party sites with a read page recommending you.","default":0},"naming":{"type":"integer","title":"Naming","description":"Third-party sites with a read page naming you.","default":0},"total":{"type":"integer","title":"Total","description":"Third-party sites with a read page.","default":0}},"type":"object","required":["count","naming","total"],"title":"SourceRecommending"},"SourceRow":{"properties":{"domain":{"type":"string","title":"Domain"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"},"source_type":{"type":"string","title":"Source Type"},"citations":{"type":"integer","title":"Citations"},"answers":{"type":"integer","title":"Answers"},"engines":{"items":{"type":"string"},"type":"array","title":"Engines"},"pages":{"$ref":"#/components/schemas/SourcePagesRead"}},"type":"object","required":["domain","rank","source_type","citations","answers","engines","pages"],"title":"SourceRow"},"SourceSiteName":{"properties":{"brand_key":{"type":"string","title":"Brand Key"},"name":{"type":"string","title":"Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"is_you":{"type":"boolean","title":"Is You"},"pages":{"type":"integer","title":"Pages"},"share_pct":{"type":"integer","title":"Share Pct"}},"type":"object","required":["brand_key","name","domain","is_you","pages","share_pct"],"title":"SourceSiteName"},"SourceTierOption":{"properties":{"value":{"type":"string","title":"Value"},"label":{"type":"string","title":"Label"},"third_party":{"type":"boolean","title":"Third Party"}},"type":"object","required":["value","label","third_party"],"title":"SourceTierOption","description":"One source tier of the report's vocabulary: its id, its word, and\nwhether its citations count as third-party presence."},"SourceTierRollup":{"properties":{"tier":{"type":"string","maxLength":64,"minLength":1,"title":"Tier"},"cite_count":{"type":"integer","minimum":0.0,"title":"Cite Count","description":"Citations represented by this source or tier."},"citation_share_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Citation Share Pct","description":"This tier's share of all citations, rounded half up."},"brand_cites":{"type":"integer","minimum":0.0,"title":"Brand Cites"},"competitor_cites":{"type":"integer","minimum":0.0,"title":"Competitor Cites"},"read_cites":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Read Cites"},"read_brand_cites":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Read Brand Cites"},"read_competitor_cites":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Read Competitor Cites"},"brand_share":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Brand Share"},"distinct_engines":{"type":"integer","minimum":0.0,"title":"Distinct Engines"},"distinct_queries":{"type":"integer","minimum":0.0,"title":"Distinct Queries"},"intrinsic_weight":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Intrinsic Weight"},"in_scan_weight":{"type":"number","minimum":0.0,"title":"In Scan Weight"},"normalized_in_scan_weight":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Normalized In Scan Weight"},"composite_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Composite Score"},"importance_status":{"type":"string","enum":["Critical","High","Mid","Low"],"title":"Importance Status"},"market_state":{"type":"string","enum":["you_own","leading","balanced","rivals_lead","rivals_own","inactive"],"title":"Market State"},"is_gap":{"type":"boolean","title":"Is Gap"},"is_opportunity":{"type":"boolean","title":"Is Opportunity","default":false},"distinct_source_count":{"type":"integer","minimum":0.0,"title":"Distinct Source Count","description":"Distinct sources in this tier."},"top_cited_domains":{"items":{"type":"string"},"type":"array","maxItems":3,"title":"Top Cited Domains"},"top_domains":{"items":{"$ref":"#/components/schemas/SourceDomainCite"},"type":"array","maxItems":7,"title":"Top Domains"},"top_non_citing_domains":{"items":{"type":"string"},"type":"array","maxItems":3,"title":"Top Non Citing Domains"}},"type":"object","required":["tier","cite_count","citation_share_pct","brand_cites","competitor_cites","read_cites","read_brand_cites","read_competitor_cites","brand_share","distinct_engines","distinct_queries","intrinsic_weight","in_scan_weight","normalized_in_scan_weight","composite_score","importance_status","market_state","is_gap","is_opportunity","distinct_source_count","top_cited_domains","top_domains","top_non_citing_domains"],"title":"SourceTierRollup"},"SourceWorthRow":{"properties":{"domain":{"type":"string","title":"Domain"},"source_type":{"anyOf":[{"type":"string","enum":["industry_authority","review","regulatory","media","educational","community","consulting","social","vendor","directory","unclassified"]},{"type":"string","const":"corporate"}],"title":"Source Type"},"title":{"type":"string","title":"Title"},"reason":{"type":"string","title":"Reason"},"citations":{"type":"integer","title":"Citations"},"action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Action Id"},"insight":{"anyOf":[{"$ref":"#/components/schemas/ServedInsight"},{"type":"null"}],"description":"The outreach that fits the source on its route, a listing or a pitch, and the work filed from it."}},"type":"object","required":["domain","source_type","title","reason","citations","action_id","insight"],"title":"SourceWorthRow"},"SourcesHallOfFame":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"rows":{"items":{"$ref":"#/components/schemas/SourceMedals"},"type":"array","title":"Rows"}},"type":"object","required":["meta","next_cursor","total","limit","offset","rows"],"title":"SourcesHallOfFame","examples":[{"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"rows":[],"total":0}]},"SourcesRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"withheld":{"items":{"type":"integer"},"type":"array","title":"Withheld","description":"Ranks present in the module whose rows are withheld."},"rows":{"items":{"$ref":"#/components/schemas/SourceRow"},"type":"array","title":"Rows"},"state":{"type":"string","enum":["complete","partial","unavailable"],"title":"State"}},"type":"object","required":["meta","next_cursor","total","limit","offset","withheld","rows","state"],"title":"SourcesRead"},"StackTool":{"properties":{"name":{"type":"string","title":"Name","description":"The detected tool's public name."},"category":{"type":"string","enum":["cms","website builder","forms","email marketing","crm","booking","live chat","analytics","heatmaps","consent","ads","other"],"title":"Category","description":"The tool's primary role on the site."},"evidence":{"items":{"type":"string"},"type":"array","title":"Evidence","description":"Page URLs and signal sources, or public DNS records."}},"type":"object","required":["name","category","evidence"],"title":"StackTool"},"Standing":{"properties":{"state":{"type":"string","enum":["ready","missing","not_set"],"title":"State","description":"Whether this side was measured at issue."},"heralded_score":{"anyOf":[{"$ref":"#/components/schemas/EditionFigure"},{"type":"null"}],"description":"The Heralded Score."},"mentioned":{"anyOf":[{"$ref":"#/components/schemas/EditionFigure"},{"type":"null"}],"description":"Share of answers naming the brand."},"recommended":{"anyOf":[{"$ref":"#/components/schemas/EditionFigure"},{"type":"null"}],"description":"Share of answers recommending the brand."},"understood":{"anyOf":[{"$ref":"#/components/schemas/EditionFigure"},{"type":"null"}],"description":"Share of checked facts AI states correctly; AI side only."},"praised":{"anyOf":[{"$ref":"#/components/schemas/EditionFigure"},{"type":"null"}],"description":"Share of answers speaking well of the brand; AI side only."},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank","description":"The brand's place among tracked brands by score."},"rank_of":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank Of","description":"Tracked brands with a score."},"trend":{"items":{"$ref":"#/components/schemas/TrendPoint"},"type":"array","title":"Trend","description":"The score by weekly report, oldest first."}},"type":"object","required":["state","heralded_score","mentioned","recommended","understood","praised","rank","rank_of","trend"],"title":"Standing","description":"Where the brand stood on one side when the report issued."},"StandingRow":{"properties":{"brand_key":{"type":"string","title":"Brand Key"},"brand_name":{"type":"string","title":"Brand Name"},"is_subject":{"type":"boolean","title":"Is Subject"},"named":{"type":"integer","title":"Named"},"picked":{"type":"integer","title":"Picked"},"picked_answers":{"type":"integer","title":"Picked Answers"},"decided_answers":{"type":"integer","title":"Decided Answers"},"answers":{"type":"integer","title":"Answers"},"prompts_won":{"type":"integer","title":"Prompts Won"}},"type":"object","required":["brand_key","brand_name","is_subject","named","picked","picked_answers","decided_answers","answers","prompts_won"],"title":"StandingRow","description":"One brand on the Who wins list (DATA-3)."},"StartAudit":{"properties":{"domain":{"type":"string","maxLength":253,"minLength":1,"title":"Domain"},"url":{"anyOf":[{"type":"string","maxLength":2048,"minLength":1},{"type":"null"}],"title":"Url","description":"The page to audit, kept whole with its path and token. It must be on domain's site. Without it the audit reads the site from its homepage."},"preview":{"type":"boolean","title":"Preview","description":"Audit a draft that is not yet published. The checks that decide whether search engines may index the site (noindex, pages missing from the sitemap, orphan pages and robots.txt closing crawlers) are left out of the score; every other check runs as on a live site.","default":false},"brand_name":{"type":"string","maxLength":120,"minLength":1,"title":"Brand Name"},"category":{"type":"string","maxLength":160,"minLength":1,"title":"Category"},"queries":{"items":{"type":"string","maxLength":200,"minLength":1},"type":"array","maxItems":20,"minItems":20,"title":"Queries"},"description":{"type":"string","maxLength":2000,"minLength":1,"title":"Description"},"target_buyer":{"type":"string","maxLength":160,"minLength":1,"title":"Target Buyer"},"differentiator":{"type":"string","maxLength":2000,"minLength":1,"title":"Differentiator"},"competitors":{"items":{"$ref":"#/components/schemas/AuditCompetitor"},"type":"array","maxItems":5,"title":"Competitors"},"tone":{"$ref":"#/components/schemas/AuditTone"}},"additionalProperties":false,"type":"object","required":["domain","brand_name","category","queries","description","target_buyer","differentiator","competitors","tone"],"title":"StartAudit"},"StartQuickAudit":{"properties":{"domain":{"type":"string","maxLength":253,"minLength":1,"title":"Domain","description":"The website domain to audit. URLs are normalized to a domain."},"url":{"anyOf":[{"type":"string","maxLength":2048,"minLength":1},{"type":"null"}],"title":"Url","description":"The page to audit, kept whole with its path and token. It must be on domain's site. Without it the audit reads the site from its homepage."},"preview":{"type":"boolean","title":"Preview","description":"Audit a draft that is not yet published. The checks that decide whether search engines may index the site (noindex, pages missing from the sitemap, orphan pages and robots.txt closing crawlers) are left out of the score; every other check runs as on a live site.","default":false}},"additionalProperties":false,"type":"object","required":["domain"],"title":"StartQuickAudit"},"StartSnapshot":{"properties":{"domain":{"type":"string","maxLength":253,"minLength":1,"title":"Domain"},"brand_name":{"type":"string","maxLength":120,"minLength":1,"title":"Brand Name"},"category":{"type":"string","maxLength":160,"minLength":1,"title":"Category"},"queries":{"items":{"type":"string","maxLength":200,"minLength":1},"type":"array","maxItems":20,"minItems":20,"title":"Queries"},"competitors":{"items":{"type":"string","maxLength":200,"minLength":1},"type":"array","maxItems":5,"title":"Competitors","description":"Ignored: a Snapshot ranks the competitors its answers name.","deprecated":true},"runs_per_prompt":{"type":"integer","enum":[1,2],"title":"Runs Per Prompt","default":2}},"additionalProperties":false,"type":"object","required":["domain","brand_name","category","queries"],"title":"StartSnapshot"},"StartedAudit":{"properties":{"scan_id":{"type":"string","format":"uuid","title":"Scan Id"}},"type":"object","required":["scan_id"],"title":"StartedAudit"},"StartedSnapshot":{"properties":{"scan_id":{"type":"string","format":"uuid","title":"Scan Id"},"share_id":{"type":"string","format":"uuid","title":"Share Id"}},"type":"object","required":["scan_id","share_id"],"title":"StartedSnapshot"},"StatementPart":{"properties":{"key":{"type":"string","title":"Key","description":"The part's stable key, kept across rewordings of its meaning."},"wording":{"type":"string","title":"Wording","description":"The part as the latest report measured it."},"quote":{"anyOf":[{"$ref":"#/components/schemas/QuotedLine"},{"type":"null"}],"description":"A verbatim passage from the measured evidence."},"verdicts":{"$ref":"#/components/schemas/Verdicts","description":"Answer counts for each verdict; doesnt_say counts answers naming the brand that never mention the part."},"trend":{"$ref":"#/components/schemas/ClaimTrend","description":"The comparison with the earlier measured period."}},"type":"object","required":["key","wording","quote","verdicts","trend"],"title":"StatementPart","description":"One part of a profile statement, as the latest report measured it."},"StrategyRead":{"properties":{"brand_id":{"type":"string","format":"uuid","title":"Brand Id","description":"The brand's id."},"goal":{"anyOf":[{"$ref":"#/components/schemas/Goal"},{"type":"null"}],"description":"The current revision of the goal; null before one."},"revisions":{"items":{"$ref":"#/components/schemas/GoalRevisionRead"},"type":"array","title":"Revisions","description":"Every revision, newest first, the current one included. Figures never compare across two."},"focus":{"$ref":"#/components/schemas/Focus","description":"The stars, at most `limit` of each kind."},"moving_away_from":{"items":{"type":"string"},"type":"array","title":"Moving Away From","description":"Labels the brand no longer wants to be described by."}},"type":"object","required":["brand_id","goal","revisions","focus","moving_away_from"],"title":"StrategyRead"},"StyleCardRead":{"properties":{"style":{"type":"string","enum":["mounted","strip","band"],"title":"Style","description":"Social card layout."},"ready":{"type":"boolean","title":"Ready","description":"Whether a rendered card is available to download.","default":false},"state":{"type":"string","enum":["pending","ready","failed"],"title":"State","description":"State of the latest render request.","default":"pending"}},"type":"object","required":["style","ready","state"],"title":"StyleCardRead"},"SubQuestionCoverage":{"properties":{"covered":{"type":"integer","minimum":0.0,"title":"Covered","default":0},"total":{"type":"integer","minimum":0.0,"title":"Total","default":0},"pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct"}},"type":"object","required":["covered","total","pct"],"title":"SubQuestionCoverage","description":"How much of a topic one page answers. `pct` is NULL when there is\nnothing to cover, which is not the same as covering none of it."},"SubjectAddress":{"properties":{"kind":{"type":"string","maxLength":100,"pattern":"^[a-z][a-z0-9_-]*$","title":"Kind","description":"Object kind, or dashboard for a Command Center page."},"id":{"type":"string","maxLength":4096,"minLength":1,"pattern":"\\S","title":"Id","description":"Object id or dashboard page name."},"scope":{"additionalProperties":{"type":"string"},"type":"object","maxProperties":30,"title":"Scope","description":"Active page or panel filters."}},"additionalProperties":false,"type":"object","required":["kind","id"],"title":"SubjectAddress"},"SurfaceAsOf":{"properties":{"scan_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Scan Id","description":"The result's scan, null for a timestamp-only result."},"at":{"type":"string","format":"date-time","title":"At","description":"When the displayed result was measured."}},"type":"object","required":["scan_id","at"],"title":"SurfaceAsOf"},"SurfaceFreshness":{"properties":{"as_of":{"anyOf":[{"$ref":"#/components/schemas/SurfaceAsOf"},{"type":"null"}],"description":"The result displayed here."},"partial":{"type":"boolean","title":"Partial","description":"The displayed report is partial.","default":false},"updating":{"type":"boolean","title":"Updating","description":"A newer attempt exists whose result is not yet displayed.","default":false},"last_attempt_failed":{"type":"boolean","title":"Last Attempt Failed","description":"The newest attempt failed; any displayed result is retained.","default":false}},"type":"object","required":["as_of","partial","updating","last_attempt_failed"],"title":"SurfaceFreshness"},"Target":{"properties":{"kind":{"type":"string","enum":["prompt","keyword"],"title":"Kind"},"uid":{"type":"string","format":"uuid","title":"Uid"},"engine":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Engine"},"metric":{"type":"string","enum":["recommended","rank"],"title":"Metric"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"}},"type":"object","required":["kind","uid","engine","metric","language"],"title":"Target"},"TaskEvidence":{"properties":{"prompts":{"items":{"$ref":"#/components/schemas/TaskPromptEvidence"},"type":"array","title":"Prompts"},"answers_link":{"anyOf":[{"$ref":"#/components/schemas/AnswersLink"},{"type":"null"}]}},"type":"object","required":["prompts","answers_link"],"title":"TaskEvidence"},"TaskNote":{"properties":{"whats_happening":{"type":"string","title":"Whats Happening"},"why_it_matters":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Why It Matters"},"what_ill_do":{"type":"string","title":"What Ill Do"},"what_i_need_from_you":{"type":"string","title":"What I Need From You"},"how_well_know":{"type":"string","title":"How Well Know"},"short_form":{"type":"string","title":"Short Form"}},"type":"object","required":["whats_happening","why_it_matters","what_ill_do","what_i_need_from_you","how_well_know","short_form"],"title":"TaskNote"},"TaskPromptEvidence":{"properties":{"prompt_uid":{"type":"string","format":"uuid","title":"Prompt Uid"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"},"named_count":{"type":"integer","title":"Named Count","description":"Answers in the selection that name the brand."},"answer_count":{"type":"integer","title":"Answer Count","description":"Answers supporting this prompt or evidence row."},"answers_link":{"$ref":"#/components/schemas/AnswersLink"}},"type":"object","required":["prompt_uid","text","named_count","answer_count","answers_link"],"title":"TaskPromptEvidence"},"ThirdPartyOpportunity":{"properties":{"source_domain":{"type":"string","title":"Source Domain"},"tier":{"type":"string","title":"Tier"},"opportunity_priority":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Opportunity Priority"},"citation_count":{"type":"integer","minimum":0.0,"title":"Citation Count","description":"Citation occurrences of this page or source in the scan."},"brand_cites":{"type":"integer","minimum":0.0,"title":"Brand Cites"},"competitor_cites":{"type":"integer","minimum":0.0,"title":"Competitor Cites"},"read_cites":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Read Cites"},"read_brand_cites":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Read Brand Cites"},"read_competitor_cites":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Read Competitor Cites"},"read_recommend_cites":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Read Recommend Cites"},"ranked_on_footprint_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ranked On Footprint Only"},"distinct_queries":{"type":"integer","minimum":0.0,"title":"Distinct Queries"},"distinct_engines":{"type":"integer","minimum":0.0,"title":"Distinct Engines"},"brand_share":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Brand Share"},"why_it_matters":{"type":"string","title":"Why It Matters"},"sample_urls":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Sample Urls"},"sample_links":{"items":{"$ref":"#/components/schemas/CitationSourceLink"},"type":"array","maxItems":5,"title":"Sample Links"},"total_queries":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Total Queries"},"route":{"anyOf":[{"type":"string","enum":["pitch","listing","partnership","community"]},{"type":"null"}],"title":"Route"},"route_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Route Reason"}},"type":"object","required":["source_domain","tier","opportunity_priority","citation_count","brand_cites","competitor_cites","read_cites","read_brand_cites","read_competitor_cites","read_recommend_cites","ranked_on_footprint_only","distinct_queries","distinct_engines","brand_share","why_it_matters","sample_urls","sample_links","total_queries","route","route_reason"],"title":"ThirdPartyOpportunity"},"ThirdPartyOpportunitySection":{"properties":{"status":{"type":"string","enum":["ready","unavailable"],"title":"Status"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"items":{"items":{"$ref":"#/components/schemas/ThirdPartyOpportunity"},"type":"array","maxItems":15,"title":"Items"},"unclassified_diagnostic":{"anyOf":[{"$ref":"#/components/schemas/UnclassifiedSourceDiagnostic"},{"type":"null"}]}},"additionalProperties":false,"type":"object","required":["status","message","items","unclassified_diagnostic"],"title":"ThirdPartyOpportunitySection"},"ThreadStepViewer":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The visible activity event."},"actor_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor Name","description":"The name this caller may see, null for a hidden or unavailable account."},"by_viewer":{"type":"boolean","title":"By Viewer","description":"Whether this caller performed the event."}},"type":"object","required":["id","actor_name","by_viewer"],"title":"ThreadStepViewer"},"TimelineDay":{"properties":{"date":{"type":"string","format":"date","title":"Date","description":"The observation day in UTC."},"lead":{"$ref":"#/components/schemas/TimelineItem","description":"The day's lead observation."},"others":{"type":"integer","title":"Others","description":"Other observations on this day."}},"type":"object","required":["date","lead","others"],"title":"TimelineDay"},"TimelineItem":{"properties":{"id":{"type":"string","title":"Id","description":"Stable identity of this observation in the week."},"kind":{"type":"string","enum":["change","result","competitor"],"title":"Kind","description":"A change, a work result or a competitor move."},"observed_at":{"type":"string","format":"date-time","title":"Observed At","description":"When the event was observed."},"event":{"type":"string","title":"Event","description":"The source's observation kind or result signal."},"target":{"anyOf":[{"$ref":"#/components/schemas/V1ChangeTarget"},{"type":"null"}],"description":"The subject and filters supporting the observation."},"action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Action Id","description":"The work behind a result; null for other observations."},"work_href":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Work Href","description":"Link to that work; null for other observations."},"result":{"anyOf":[{"$ref":"#/components/schemas/ResultStep"},{"type":"null"}],"description":"The kind-specific result step, retaining its measured state."}},"type":"object","required":["id","kind","observed_at","event","target","action_id","work_href","result"],"title":"TimelineItem"},"TodaySuggestion":{"properties":{"row":{"$ref":"#/components/schemas/WorkRowResponse","description":"The suggested work and its existing start controls."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"The observation the work leads with, null where it rests on none."},"cost":{"type":"integer","title":"Cost","description":"Content credits needed to start; zero means free."}},"type":"object","required":["row","reason","cost"],"title":"TodaySuggestion"},"TodayTeamDecision":{"properties":{"row":{"$ref":"#/components/schemas/WorkRowResponse","description":"The open decision's current work row."},"assignee_name":{"type":"string","title":"Assignee Name","description":"The assignee's first name, or their safe display name."},"age_days":{"type":"integer","title":"Age Days","description":"UTC calendar days since the current ask began."}},"type":"object","required":["row","assignee_name","age_days"],"title":"TodayTeamDecision"},"ToneSplit":{"properties":{"positive":{"type":"integer","title":"Positive"},"neutral":{"type":"integer","title":"Neutral"},"negative":{"type":"integer","title":"Negative"},"named":{"type":"integer","title":"Named"}},"type":"object","required":["positive","neutral","negative","named"],"title":"ToneSplit","description":"The answers naming the brand, split three ways. `neutral` is the stored\nvalence the page calls balanced: no valuation, or one favouring no side."},"TopicCountryDemand":{"properties":{"country":{"type":"string","title":"Country"},"demand":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Demand"},"volume_partial":{"type":"boolean","title":"Volume Partial"}},"type":"object","required":["country","demand","volume_partial"],"title":"TopicCountryDemand"},"TopicOwnPage":{"properties":{"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id"},"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"questions_answered":{"type":"integer","title":"Questions Answered"},"question_total":{"type":"integer","title":"Question Total","description":"All questions mapped to this owned page."},"citations":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Citations"},"best_google_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Google Rank"},"search_clicks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Clicks"},"ai_visits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ai Visits"}},"type":"object","required":["document_id","url","title","questions_answered","question_total","citations","best_google_rank","search_clicks","ai_visits"],"title":"TopicOwnPage"},"TopicPiece":{"properties":{"action_id":{"type":"string","title":"Action Id"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"piece_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Piece Id"},"stage":{"type":"string","title":"Stage"},"stage_words":{"type":"string","title":"Stage Words"}},"type":"object","required":["action_id","language","piece_id","stage","stage_words"],"title":"TopicPiece","description":"The piece a Missing topic already has, in the words Studio uses.\n\n`piece_id` is null while the order is still being placed: the brand's\nfirst order is dispatched before its writing profile exists, and the\npiece row is written once the worker has one."},"TopicQuestionResult":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"segment":{"type":"string","title":"Segment"},"state":{"type":"string","enum":["answered","unanswered","unknown"],"title":"State"},"pages":{"items":{"type":"string"},"type":"array","title":"Pages"},"insight":{"anyOf":[{"$ref":"#/components/schemas/ServedInsight"},{"type":"null"}],"description":"On an unanswered question: the work its topic's verdict fits, a page for the topic or a rewrite of its closest page, and the work filed from it."}},"type":"object","required":["key","label","segment","state","pages","insight"],"title":"TopicQuestionResult"},"TopicScore":{"properties":{"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value"},"band":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Band"},"change":{"anyOf":[{"$ref":"#/components/schemas/FigureChange"},{"type":"null"}]},"mentioned":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentioned"},"recommended":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Recommended"},"state":{"type":"string","title":"State","description":"The score's state, as the figures read states it: `not_measured` or `too_few_answers` below the measurement gate. Search is `not_scored`.","x-extensible-enum":["measured","too_few_answers","calibrating","first_report","not_comparable","not_measured","pending","not_scored"]}},"type":"object","required":["value","band","change","mentioned","recommended","state"],"title":"TopicScore","description":"One side of a topic's Heralded Score."},"TopicScores":{"properties":{"all":{"$ref":"#/components/schemas/TopicScore"},"ai":{"$ref":"#/components/schemas/TopicScore"},"search":{"$ref":"#/components/schemas/TopicScore"}},"type":"object","required":["all","ai","search"],"title":"TopicScores","description":"The sides of a topic's Heralded Score. A side not measured has no value."},"TopicStanding":{"properties":{"name":{"type":"string","title":"Name","description":"The brand's name."},"is_you":{"type":"boolean","title":"Is You","description":"Whether this is your own brand rather than a competitor."},"scores":{"$ref":"#/components/schemas/TopicScores"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"The brand's website domain; null where Heralded has none."},"mentioned_change":{"anyOf":[{"$ref":"#/components/schemas/FigureChange"},{"type":"null"}],"description":"How its Mentioned moved on `side`."},"recommended_change":{"anyOf":[{"$ref":"#/components/schemas/FigureChange"},{"type":"null"}],"description":"How its Recommended moved on `side`."}},"type":"object","required":["name","is_you","scores","domain","mentioned_change","recommended_change"],"title":"TopicStanding","description":"A brand's score on one topic: the brand, or a rival the brand tracks."},"TrailEntry":{"properties":{"signal":{"anyOf":[{"type":"string","enum":["live","crawled","ranked","search_console","cited","moved"]},{"type":"string","const":"measured"}],"title":"Signal","description":"What was watched. `measured` is the credited verification, the strongest entry; a site fix's verification is its `live` entry."},"state":{"type":"string","enum":["good","no_change","couldnt_check","pending"],"title":"State","description":"`good`: it happened. `no_change`: Heralded looked and it has not happened yet. `couldnt_check`: Heralded could not look, for `reason`. `pending`: nothing to say yet."},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary","description":"The line as Heralded wrote it; null while pending."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why it could not be checked; null otherwise."},"at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"At","description":"When it was observed or last looked at; for a pending measured result, when the result is due, where that is known."}},"type":"object","required":["signal","state","summary","reason","at"],"title":"TrailEntry","description":"One line of what happened since the work was delivered."},"TrendBreak":{"properties":{"at":{"type":"string","format":"date","title":"At","description":"Date of the new baseline."},"parts":{"items":{"type":"string","x-extensible-enum":["engines","language","market","score_version","answer_pack_version","understood_measure","sells_to","shopping_pack_version"]},"type":"array","title":"Parts","description":"Instrument parts that changed."},"engines_added":{"items":{"type":"string"},"type":"array","title":"Engines Added","description":"Engines added at this baseline."},"engines_removed":{"items":{"type":"string"},"type":"array","title":"Engines Removed","description":"Engines removed at this baseline."},"comparable":{"type":"boolean","title":"Comparable","description":"Whether the changed instrument still permits comparison."}},"type":"object","required":["at","parts","engines_added","engines_removed","comparable"],"title":"TrendBreak"},"TrendPoint":{"properties":{"at":{"type":"string","format":"date-time","title":"At","description":"When the weekly report completed."},"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value","description":"The Heralded Score that report issued."}},"type":"object","required":["at","value"],"title":"TrendPoint"},"UnclassifiedSourceDiagnostic":{"properties":{"citation_count":{"type":"integer","minimum":0.0,"title":"Citation Count","description":"Citation occurrences of this page or source in the scan."},"citation_share":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Citation Share"},"sample_domains":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Sample Domains"},"message":{"type":"string","title":"Message"}},"type":"object","required":["citation_count","citation_share","sample_domains","message"],"title":"UnclassifiedSourceDiagnostic"},"UnmeasuredPage":{"properties":{"url":{"type":"string","title":"Url"},"detail":{"type":"string","title":"Detail"}},"type":"object","required":["url","detail"],"title":"UnmeasuredPage"},"UsageBrand":{"properties":{"brand_id":{"type":"string","title":"Brand Id"},"domain":{"type":"string","title":"Domain"},"paused":{"type":"boolean","title":"Paused"},"prompts_used":{"type":"integer","title":"Prompts Used"},"topics_used":{"type":"integer","title":"Topics Used","description":"Active topics in this brand’s live profiles, including while paused."},"prompts_reserved":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompts Reserved"},"segments":{"items":{"$ref":"#/components/schemas/UsageSegment"},"type":"array","title":"Segments","description":"The brand's live segments, Default first, and the topics each tracks. Tracked counts are zero for a reader without read access.","default":[]},"credits_used":{"type":"integer","title":"Credits Used"},"credits_reserved":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Reserved"},"credits_left":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Left"},"first_screen_rewrites":{"$ref":"#/components/schemas/UsageFirstScreen"}},"type":"object","required":["brand_id","domain","paused","prompts_used","topics_used","prompts_reserved","segments","credits_used","credits_reserved","credits_left","first_screen_rewrites"],"title":"UsageBrand","description":"One live brand's part of the two meters."},"UsageCapacity":{"properties":{"used":{"type":"integer","title":"Used","description":"Active topics or brands across the workspace's reading brands."},"limit":{"type":"integer","title":"Limit","description":"The workspace limit for this capacity, including paid topic blocks for topics."}},"type":"object","required":["used","limit"],"title":"UsageCapacity"},"UsageContentCredits":{"properties":{"balance":{"type":"integer","title":"Balance"},"purchased_balance":{"type":"integer","title":"Purchased Balance"},"included_per_month":{"type":"integer","title":"Included Per Month"},"used_this_month":{"type":"integer","title":"Used This Month"},"used_this_period":{"type":"integer","title":"Used This Period"},"in_reserve":{"type":"integer","title":"In Reserve"},"months":{"items":{"$ref":"#/components/schemas/UsageCreditMonth"},"type":"array","title":"Months"},"next_top_up_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Top Up At"}},"type":"object","required":["balance","purchased_balance","included_per_month","used_this_month","used_this_period","in_reserve","months","next_top_up_at"],"title":"UsageContentCredits","description":"A balance and a spend history, which are different questions.\n\n`balance` is what is left to spend now; `months` is what was spent, and a\nmonth a workspace bought credits in shows the spend, not the purchase.\n`purchased_balance` is the part of `balance` a pack paid for or Heralded\ngranted, spent after the allowance and never expiring with the period\n(#2367): the page draws one bar and splits the balance in its note."},"UsageCreditMonth":{"properties":{"month":{"type":"string","title":"Month"},"used":{"type":"integer","title":"Used"}},"type":"object","required":["month","used"],"title":"UsageCreditMonth"},"UsageFirstScreen":{"properties":{"used":{"type":"integer","title":"Used","description":"First-screen rewrites the brand has started this month. A draft that could not be made returns its place."},"limit":{"type":"integer","title":"Limit","description":"The most free first-screen rewrites the brand gets in a month. Zero without a plan."},"resets_at":{"type":"string","title":"Resets At","description":"When the month turns and the count starts again."}},"type":"object","required":["used","limit","resets_at"],"title":"UsageFirstScreen","description":"A brand's free first-screen rewrites this calendar month (UTC)."},"UsagePrompts":{"properties":{"used":{"type":"integer","title":"Used"},"pool":{"type":"integer","title":"Pool"},"free":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Free"}},"type":"object","required":["used","pool","free"],"title":"UsagePrompts","description":"The prompts the organization's brands read together, of the most its\nplan reads. A prompt tracked in a second segment counts twice."},"UsageSegment":{"properties":{"id":{"type":"string","title":"Id","description":"The segment's id."},"name":{"type":"string","title":"Name","description":"The segment's name."},"topics":{"$ref":"#/components/schemas/SegmentTopics"}},"type":"object","required":["id","name","topics"],"title":"UsageSegment"},"V1AISearch":{"properties":{"text":{"type":"string","title":"Text","description":"A web search the engine ran while answering this prompt."},"engine":{"type":"string","title":"Engine"},"answer_id":{"type":"string","format":"uuid","title":"Answer Id","description":"The observed answer that searched this text."},"observed_at":{"type":"string","format":"date-time","title":"Observed At","description":"When that answer completed."},"google_rank":{"$ref":"#/components/schemas/V1GoogleRank"}},"type":"object","required":["text","engine","answer_id","observed_at","google_rank"],"title":"V1AISearch"},"V1AboveTheFold":{"properties":{"url":{"type":"string","title":"Url"},"screenshot_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Screenshot Url","description":"The screenshot 3 s after load."},"load_screenshot_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Load Screenshot Url","description":"The screenshot at load."},"captured_at":{"type":"string","format":"date-time","title":"Captured At"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headline"},"offer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offer","description":"What it says is sold; null where it does not say."},"audience":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audience","description":"Who it says it is for."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why choose it."},"call_to_action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call To Action","description":"The hero's next step."},"header_action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Header Action"},"hero_action_late":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Hero Action Late","description":"The hero's action appeared only after load; null where not compared."},"regions":{"$ref":"#/components/schemas/V1Regions","description":"Where the headline and action sit, as fractions."},"proof_on_screen":{"type":"boolean","title":"Proof On Screen"},"design":{"$ref":"#/components/schemas/V1Design"},"headline_specific":{"type":"string","enum":["pass","fail","unclear"],"title":"Headline Specific"},"cta_actionable":{"type":"string","enum":["pass","fail","unclear"],"title":"Cta Actionable"}},"type":"object","required":["url","screenshot_url","load_screenshot_url","captured_at","category","headline","offer","audience","reason","call_to_action","header_action","hero_action_late","regions","proof_on_screen","design","headline_specific","cta_actionable"],"title":"V1AboveTheFold","description":"What a visitor sees before scrolling, read off the page's screenshot."},"V1Action":{"properties":{"waiting_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Waiting Since","description":"When the current ask began; null outside your_input."},"route":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Route","description":"Destination for the action or its recovery."},"demand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Demand","description":"What the current work asks of you."},"first_citation":{"anyOf":[{"$ref":"#/components/schemas/FirstCitation"},{"type":"null"}],"description":"First qualifying citation of the delivered page."},"citation_count":{"type":"integer","title":"Citation Count","description":"Distinct engine and prompt citation pairs before the list cap.","default":0},"write_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Write Language"},"write_language_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Write Language Source"},"write_language_locked":{"type":"boolean","title":"Write Language Locked","default":false},"placed_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Placed Position","description":"Position in the brand's proposed order; null when Heralded ranks it."},"not_seen_since_run":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Not Seen Since Run","description":"First read that stopped seeing this suggestion; null when seen."},"evidence":{"anyOf":[{"$ref":"#/components/schemas/TaskEvidence"},{"type":"null"}],"description":"Linked prompts and rendered answer counts from the latest report."},"note":{"anyOf":[{"$ref":"#/components/schemas/TaskNote"},{"type":"null"}],"description":"Task explanation with a live job step."},"id":{"type":"string","format":"uuid","title":"Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"},"kind":{"type":"string","title":"Kind"},"member":{"anyOf":[{"type":"string","enum":["writer","publicist","engineer","analyst"]},{"type":"null"}],"title":"Member","description":"The responsible team member; null for setup and prompt replacements."},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"The action's first start by Heralded; null on dismissed work."},"delivered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Delivered At","description":"When the result went live, was sent or was published; null on dismissed work."},"paid_off_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paid Off At","description":"When verification credited a positive measured gain; null on dismissed work."},"preview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preview","description":"Up to 400 characters of draft opening, email recipient and subject, or planned change while waiting on you."},"group":{"type":"string","enum":["new","your_input","dispatched","scheduled","waiting","settled","withdrawn"],"title":"Group"},"scheduled_for":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Scheduled For","description":"The scheduled action's start date; null when the action is not scheduled."},"holder":{"anyOf":[{"type":"string","enum":["you","heralded","waiting"]},{"type":"null"}],"title":"Holder","description":"Who holds the work: you, Heralded or a third party; null when nobody holds it."},"stage":{"type":"string","enum":["observe","decide","do","verify"],"title":"Stage","description":"The work's stage: observe, decide, do or verify."},"outcome":{"anyOf":[{"type":"string","enum":["verified_up","no_move","not_measured","dismissed"]},{"type":"null"}],"title":"Outcome"},"grounds":{"anyOf":[{"$ref":"#/components/schemas/GroundsResponse"},{"type":"null"}],"description":"What the work rests on: its kind, its likely cause, the dated evidence, the prompt or keyword results it targets and, for best practice, the publisher guidance. Null on work filed before actions carried their grounds."},"done_when":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Done When","description":"When the work is done."},"tracking":{"items":{"type":"string","enum":["live","crawled","ranked","search_console","cited","moved"]},"type":"array","title":"Tracking","description":"What Heralded tracks once the work is live."},"gain":{"anyOf":[{"$ref":"#/components/schemas/GainResponse"},{"type":"null"}],"description":"The expected gain: its band (high, medium or low, null on work you asked for) and what the work aims at."},"focus":{"anyOf":[{"$ref":"#/components/schemas/FocusTag"},{"type":"null"}],"description":"The starred topic or competitor the work serves, or outside your focus."},"kind_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind Tag","description":"A tag on the kind of work, such as Sponsored; null on work that has none."},"ending":{"anyOf":[{"$ref":"#/components/schemas/EndingResponse"},{"type":"null"}],"description":"How the task ended, such as No reply, Stopped or Not relevant, and when; null while it is open. `outcome` keeps its meaning."},"wait":{"anyOf":[{"$ref":"#/components/schemas/WaitResponse"},{"type":"null"}],"description":"What the task waits for, on whom, until when and who acts then; null while it waits on nobody."},"created_at":{"type":"string","format":"date-time","title":"Created At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"}},"type":"object","required":["waiting_since","route","demand","first_citation","citation_count","write_language","write_language_source","write_language_locked","placed_position","not_seen_since_run","evidence","note","id","title","detail","kind","member","started_at","delivered_at","paid_off_at","preview","group","scheduled_for","holder","stage","outcome","grounds","done_when","tracking","gain","focus","kind_tag","ending","wait","created_at","completed_at"],"title":"V1Action"},"V1ActionApplication":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"state":{"type":"string","title":"State"},"provider":{"type":"string","title":"Provider"},"fix_kind":{"type":"string","title":"Fix Kind"},"desired_value":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object","title":"Desired Value"},"planned_against_value":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}],"title":"Planned Against Value","description":"The site's value when the change was planned."},"effect":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effect","description":"What applying does to the current value: `overwrite`, `remove` or `send` ask the member to confirm first."},"previous_value":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}],"title":"Previous Value"},"failure_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failure Reason"},"approved_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Approved At"},"scheduled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Scheduled At","description":"When an operation that waits for its moment, such as an email, is due."},"applied_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Applied At"},"verified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Verified At"}},"type":"object","required":["id","state","provider","fix_kind","desired_value","planned_against_value","effect","previous_value","failure_reason","approved_at","scheduled_at","applied_at","verified_at"],"title":"V1ActionApplication"},"V1ActionDetail":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"waiting_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Waiting Since","description":"When the current ask began; null outside your_input."},"route":{"type":"string","title":"Route"},"demand":{"type":"string","title":"Demand","description":"What the work waits on, in a line."},"first_citation":{"anyOf":[{"$ref":"#/components/schemas/FirstCitation"},{"type":"null"}],"description":"First qualifying citation of the delivered page."},"citation_count":{"type":"integer","title":"Citation Count","description":"Distinct engine and prompt citation pairs before the list cap.","default":0},"write_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Write Language"},"write_language_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Write Language Source"},"write_language_locked":{"type":"boolean","title":"Write Language Locked","default":false},"placed_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Placed Position","description":"Position in the brand's proposed order; null when Heralded ranks it."},"not_seen_since_run":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Not Seen Since Run","description":"First read that stopped seeing this suggestion; null when seen."},"evidence":{"anyOf":[{"$ref":"#/components/schemas/TaskEvidence"},{"type":"null"}],"description":"Linked prompts and rendered answer counts from the latest report."},"note":{"anyOf":[{"$ref":"#/components/schemas/TaskNote"},{"type":"null"}],"description":"Task explanation with a live job step."},"id":{"type":"string","format":"uuid","title":"Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"},"kind":{"type":"string","title":"Kind"},"member":{"anyOf":[{"type":"string","enum":["writer","publicist","engineer","analyst"]},{"type":"null"}],"title":"Member","description":"The responsible team member; null for setup and prompt replacements."},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"The action's first start by Heralded; null on dismissed work."},"delivered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Delivered At","description":"When the result went live, was sent or was published; null on dismissed work."},"paid_off_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paid Off At","description":"When verification credited a positive measured gain; null on dismissed work."},"preview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preview","description":"Up to 400 characters of draft opening, email recipient and subject, or planned change while waiting on you."},"group":{"type":"string","enum":["new","your_input","dispatched","scheduled","waiting","settled","withdrawn"],"title":"Group"},"scheduled_for":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Scheduled For"},"holder":{"anyOf":[{"type":"string","enum":["you","heralded","waiting"]},{"type":"null"}],"title":"Holder","description":"Who holds the work: you, Heralded or a third party; null when nobody holds it."},"stage":{"type":"string","enum":["observe","decide","do","verify"],"title":"Stage","description":"The work's stage: observe, decide, do or verify."},"outcome":{"anyOf":[{"type":"string","enum":["verified_up","no_move","not_measured","dismissed"]},{"type":"null"}],"title":"Outcome"},"grounds":{"anyOf":[{"$ref":"#/components/schemas/GroundsResponse"},{"type":"null"}],"description":"What the work rests on: its kind, its likely cause, the dated evidence, the prompt or keyword results it targets and, for best practice, the publisher guidance. Null on work filed before actions carried their grounds."},"done_when":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Done When","description":"When the work is done."},"tracking":{"items":{"type":"string","enum":["live","crawled","ranked","search_console","cited","moved"]},"type":"array","title":"Tracking","description":"What Heralded tracks once the work is live."},"gain":{"anyOf":[{"$ref":"#/components/schemas/GainResponse"},{"type":"null"}],"description":"The expected gain: its band (high, medium or low, null on work you asked for) and what the work aims at."},"focus":{"anyOf":[{"$ref":"#/components/schemas/FocusTag"},{"type":"null"}],"description":"The starred topic or competitor the work serves, or outside your focus."},"kind_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind Tag","description":"A tag on the kind of work, such as Sponsored; null on work that has none."},"ending":{"anyOf":[{"$ref":"#/components/schemas/EndingResponse"},{"type":"null"}],"description":"How the task ended, such as No reply, Stopped or Not relevant, and when; null while it is open. `outcome` keeps its meaning."},"wait":{"anyOf":[{"$ref":"#/components/schemas/WaitResponse"},{"type":"null"}],"description":"What the task waits for, on whom, until when and who acts then; null while it waits on nobody."},"created_at":{"type":"string","format":"date-time","title":"Created At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"},"state":{"type":"string","enum":["new","accepted","in_progress","blocked","looks_resolved","done","verified_no_move","deferred","dismissed","withdrawn"],"title":"State"},"target_entity":{"type":"string","title":"Target Entity"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"impact_scale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Impact Scale"},"expected_impact_pts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expected Impact Pts","description":"Always null: the expected gain is `gain`."},"verified_impact_pts":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Verified Impact Pts"},"primary_verb":{"anyOf":[{"type":"string","enum":["dispatch","take","done","defer","dismiss","confirm","reject","restore","block","unblock","reopen"]},{"type":"string","const":"review"},{"type":"null"}],"title":"Primary Verb"},"secondary_verbs":{"items":{"type":"string","enum":["dispatch","take","done","defer","dismiss","confirm","reject","restore","block","unblock","reopen"]},"type":"array","title":"Secondary Verbs"},"job":{"$ref":"#/components/schemas/JobResponse"},"credit_cost":{"type":"integer","title":"Credit Cost"},"credits_spent":{"type":"integer","title":"Credits Spent","description":"Content credits charged to this work and not refunded."},"dispatchable":{"type":"boolean","title":"Dispatchable"},"platform":{"type":"boolean","title":"Platform"},"gate":{"anyOf":[{"type":"string","enum":["approval","review"]},{"type":"null"}],"title":"Gate"},"setup_link":{"anyOf":[{"$ref":"#/components/schemas/SetupLink"},{"type":"null"}]},"return_group":{"anyOf":[{"type":"string","enum":["new","your_input","dispatched","scheduled","waiting","settled","withdrawn"]},{"type":"null"}],"title":"Return Group"},"draft_in_flight":{"anyOf":[{"type":"string","enum":["drafting","redrafting"]},{"type":"null"}],"title":"Draft In Flight"},"piece_preview":{"anyOf":[{"$ref":"#/components/schemas/V1ActionPiecePreview"},{"type":"null"}],"description":"Compact piece state without its document or images; present on preview reads."},"asset":{"anyOf":[{"$ref":"#/components/schemas/V1Asset"},{"type":"null"}],"description":"The current asset, null before one has been made."},"targets":{"items":{"$ref":"#/components/schemas/V1ActionTarget"},"type":"array","title":"Targets","description":"Questions and searches on the requested page."},"pages_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages Remaining","description":"Affected pages still requiring a fix before paging."},"viewer":{"anyOf":[{"$ref":"#/components/schemas/ActionViewerResponse"},{"type":"null"}],"description":"The kit, redraft allowance and activity names visible to this caller."},"page":{"anyOf":[{"$ref":"#/components/schemas/ActionSection"},{"type":"null"}],"description":"The requested section page and continuation."},"section_totals":{"additionalProperties":{"type":"integer"},"type":"object","title":"Section Totals","description":"Rows in each compact section before paging."},"looks_resolved_evidence":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Looks Resolved Evidence","description":"The last observed finding when the work appears resolved."},"citations":{"items":{"$ref":"#/components/schemas/FirstCitation"},"type":"array","title":"Citations","description":"Distinct engine and stable prompt citation pairs in the publication measurement window, capped at five."},"results":{"$ref":"#/components/schemas/ActionResults","description":"Grouped observations, citation headline, connection offer and measured outcome for delivered work."},"brand_id":{"type":"string","format":"uuid","title":"Brand Id"},"segment":{"type":"string","title":"Segment"},"settled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Settled At"},"prompt_movement":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Movement"},"blocked_owner":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blocked Owner"},"check_again_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Check Again On"},"dismissal_reason":{"anyOf":[{"type":"string","enum":["not_now","too_much_work","not_relevant","already_done"]},{"type":"null"}],"title":"Dismissal Reason","description":"Why a member put the work away, while it stays put away. `not_now` defers it four weeks. `too_much_work`, `not_relevant` and `already_done` dismiss it, and `not_relevant` also stops Heralded suggesting that play for that target again. Null when no reason was given and once the work is restored."},"assignee":{"anyOf":[{"$ref":"#/components/schemas/AssigneeResponse"},{"type":"null"}]},"steps":{"items":{"$ref":"#/components/schemas/V1ActionJobStage"},"type":"array","title":"Steps"},"current_step":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Step"},"thread":{"items":{"$ref":"#/components/schemas/V1ActionStep"},"type":"array","title":"Thread"},"drafts":{"items":{"$ref":"#/components/schemas/V1ActionDraft"},"type":"array","title":"Drafts"},"current_draft_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Current Draft Version","description":"The draft version this action shows; null without a draft, or when the newest one was written for another route."},"recipient":{"anyOf":[{"$ref":"#/components/schemas/V1ArtifactRecipient"},{"type":"null"}],"description":"Who an outreach task's email is addressed to and where its address was found; null on other work."},"correspondence":{"anyOf":[{"$ref":"#/components/schemas/V1Correspondence"},{"type":"null"}],"description":"The emails of a task with a source and whose move it is; null on work that writes no email."},"application":{"anyOf":[{"$ref":"#/components/schemas/V1ActionApplication"},{"type":"null"}]},"content_piece":{"anyOf":[{"$ref":"#/components/schemas/V1ActionPiece"},{"type":"null"}]},"insight_links":{"items":{"$ref":"#/components/schemas/V1InsightLink"},"type":"array","title":"Insight Links","description":"Every scan that created or reprioritised this action, oldest first."},"checklist":{"items":{"type":"string"},"type":"array","title":"Checklist","description":"The steps you follow where Heralded drafts and applies nothing: a site check's fix as Site Health shows it, or a listing's steps. Empty on other work."},"pages":{"items":{"type":"string"},"type":"array","title":"Pages","description":"Affected page URLs, separate from the instructions in `checklist`."},"fixed_pages":{"items":{"type":"string"},"type":"array","title":"Fixed Pages","description":"Previously affected pages checked as passing by a later Website read."},"trail":{"items":{"$ref":"#/components/schemas/TrailEntry"},"type":"array","title":"Trail","description":"What happened since the work was delivered: one entry per signal in `tracking`, then the `measured` result. A site fix's measured result is its `live` entry. Empty until the work is delivered."}},"type":"object","required":["meta","waiting_since","route","demand","first_citation","citation_count","write_language","write_language_source","write_language_locked","placed_position","not_seen_since_run","evidence","note","id","title","detail","kind","member","started_at","delivered_at","paid_off_at","preview","group","scheduled_for","holder","stage","outcome","grounds","done_when","tracking","gain","focus","kind_tag","ending","wait","created_at","completed_at","state","target_entity","updated_at","impact_scale","expected_impact_pts","verified_impact_pts","primary_verb","secondary_verbs","job","credit_cost","credits_spent","dispatchable","platform","gate","setup_link","return_group","draft_in_flight","piece_preview","asset","targets","pages_remaining","looks_resolved_evidence","citations","results","brand_id","segment","settled_at","prompt_movement","blocked_owner","check_again_on","dismissal_reason","assignee","steps","current_step","thread","drafts","current_draft_version","recipient","correspondence","application","content_piece","insight_links","checklist","pages","fixed_pages","trail"],"title":"V1ActionDetail"},"V1ActionDraft":{"properties":{"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"email":{"anyOf":[{"type":"string","enum":["reminder_1","reminder_2"]},{"type":"null"}],"title":"Email","description":"Which email of a task with a source this version is for: null for the turn's leading email (the first email, or an answer), and for every draft of work that writes no email."},"turn":{"type":"integer","title":"Turn","description":"The turn of a task's emails this version is for: 0 for the first email and its reminders, otherwise an answer to an email of theirs and its reminders.","default":0},"id":{"type":"string","format":"uuid","title":"Id"},"version":{"type":"integer","title":"Version"},"type":{"type":"string","title":"Type"},"body":{"type":"string","title":"Body"},"from_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From Address","description":"The chosen From address. An empty string selects your own mail; null keeps an existing draft's sending path. Changing it creates a version requiring approval."},"english_body":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"English Body","description":"Stored English text of an outreach email draft, where translated."},"answers":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Answers","description":"For an answer to their email: the ids of the conversation's obligations it answers (`correspondence.state.obligations`), which sending its text settles. Null on every other draft, and on an answer drafted before answers were recorded."},"angle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Angle"},"revision_requested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revision Requested At"},"revision_closed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revision Closed At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"written_by":{"type":"string","enum":["heralded","member"],"title":"Written By","description":"Who wrote this version: Heralded's draft, or a member's edit.","readOnly":true},"gaps":{"items":{"$ref":"#/components/schemas/DraftGapResponse"},"type":"array","title":"Gaps","description":"What the draft still needs from a member before it can go, each gap in the order it stands. Filling one saves that gap alone.","readOnly":true}},"type":"object","required":["language","email","turn","id","version","type","body","from_address","english_body","answers","angle","revision_requested_at","revision_closed_at","created_at","written_by","gaps"],"title":"V1ActionDraft"},"V1ActionJobStage":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"line":{"type":"string","title":"Line"},"doer":{"type":"string","enum":["heralded","member","watch"],"title":"Doer"},"done_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Done At"},"status":{"type":"string","enum":["done","now","ahead","ended"],"title":"Status","description":"Where the step stands: done, now, ahead, or ended, the step an ended task had reached when it ended.","default":"ahead"},"lane":{"type":"string","enum":["main","article"],"title":"Lane","description":"main, or article for the article an outreach agreement needs, whose steps run beside the emails.","default":"main"},"events":{"items":{"$ref":"#/components/schemas/V1ActionStep"},"type":"array","title":"Events","description":"What happened at this step, oldest first, identical events as one entry. A full read carries every one and a compact read the latest five; a section read carries none, and `section=activity` with `step` pages them. An event of a kind no step owns shows under the step last finished when it happened, or the first step."},"event_count":{"type":"integer","title":"Event Count","description":"This step's entries before paging; zero on a section read.","default":0}},"type":"object","required":["key","label","line","doer","done_at","status","lane","events","event_count"],"title":"V1ActionJobStage"},"V1ActionPiece":{"properties":{"destination_hosts":{"items":{"type":"string"},"type":"array","title":"Destination Hosts","description":"Publication hosts. Defaults to the brand's owned sites, including older pieces."},"constraints":{"anyOf":[{"$ref":"#/components/schemas/PieceConstraints"},{"type":"null"}],"description":"What the order asked of the piece: the length in words, the links and the date it is needed by, such as an agreed outreach option's requirements. Null where the order asked nothing."},"words":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Words","description":"Words of prose in the current version; null before a draft."},"report":{"anyOf":[{"$ref":"#/components/schemas/WriterReport"},{"type":"null"}],"description":"Writer questions, sources and checked references; null when unavailable."},"images":{"$ref":"#/components/schemas/ImageSlots","description":"Featured image, generation results and social preview, without signed URLs."},"first_citation":{"anyOf":[{"$ref":"#/components/schemas/FirstCitation"},{"type":"null"}],"description":"First qualifying citation after publication; null while uncited."},"citations":{"items":{"$ref":"#/components/schemas/FirstCitation"},"type":"array","title":"Citations","description":"Distinct engine and stable prompt citation pairs in the publication measurement window, capped at five."},"citation_count":{"type":"integer","title":"Citation Count","description":"Distinct engine and stable prompt citation pairs in the publication measurement window, before the list cap.","default":0},"id":{"type":"string","format":"uuid","title":"Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The piece title."},"has_brief":{"type":"boolean","title":"Has Brief","description":"Whether a retained brief exists. False for new writer pieces.","default":false,"deprecated":true},"stage":{"type":"string","title":"Stage","description":"Studio stage projected from the operation and Heralded's gates.","x-extensible-enum":["ordering","researching_and_writing","applying_comments","your_review","approved","publishing","published","stopped","failed","paused"]},"format":{"type":"string","title":"Format"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"draft_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Draft Version"},"draft_content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft Content"},"fields":{"items":{"$ref":"#/components/schemas/V1ActionPieceField"},"type":"array","title":"Fields","description":"The current settled draft's format fields, in the format's order."},"draft_origin":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft Origin"},"published_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published Url"}},"type":"object","required":["destination_hosts","constraints","words","report","images","first_citation","citations","citation_count","id","title","has_brief","stage","format","language","draft_version","draft_content","fields","draft_origin","published_url"],"title":"V1ActionPiece"},"V1ActionPieceField":{"properties":{"name":{"type":"string","title":"Name","description":"The format field's name, such as `title` or `meta_description`."},"label":{"type":"string","title":"Label","description":"The field's label, as supplied by the writing format."},"value":{"type":"string","title":"Value","description":"The field's text on the current settled draft."}},"type":"object","required":["name","label","value"],"title":"V1ActionPieceField"},"V1ActionPiecePreview":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The current-generation piece identifier."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The piece title."},"has_brief":{"type":"boolean","title":"Has Brief","description":"Whether a retained brief exists. False for new writer pieces.","deprecated":true},"stage":{"type":"string","title":"Stage","description":"The current detailed piece stage.","x-extensible-enum":["ordering","researching_and_writing","applying_comments","your_review","approved","publishing","published","stopped","failed","paused"]},"format":{"type":"string","title":"Format","description":"The writing format."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"The piece language."},"draft_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Draft Version","description":"The settled draft version, null before a draft exists."},"published_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published Url","description":"The recorded live URL, null before publication."}},"type":"object","required":["id","title","has_brief","stage","format","language","draft_version","published_url"],"title":"V1ActionPiecePreview"},"V1ActionStep":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"kind":{"type":"string","title":"Kind"},"actor":{"type":"string","title":"Actor"},"summary":{"type":"string","title":"Summary"},"detail":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}],"title":"Detail"},"occurred_at":{"type":"string","format":"date-time","title":"Occurred At"},"repeat_count":{"type":"integer","minimum":1.0,"title":"Repeat Count","description":"Identical visible activity events represented by this entry.","default":1},"retry_after_failure":{"type":"boolean","title":"Retry After Failure","description":"This unblock requested a retry after a failed draft.","default":false},"line":{"type":"string","title":"Line","description":"The event in words for this reader: who did it and what they did, \"You\" where the reader took the step, dates in words and no version numbers. `summary` is the same line for no reader in particular, worded when it is read.","default":""},"tone":{"anyOf":[{"type":"string","const":"failure"},{"type":"null"}],"title":"Tone","description":"failure for an event that failed; null otherwise."}},"type":"object","required":["id","kind","actor","summary","detail","occurred_at","repeat_count","retry_after_failure","line","tone"],"title":"V1ActionStep"},"V1ActionTarget":{"properties":{"kind":{"type":"string","enum":["prompt","keyword"],"title":"Kind","description":"Whether the target is an AI question or Google search."},"uid":{"type":"string","format":"uuid","title":"Uid","description":"The stable question or keyword identifier."},"text":{"type":"string","title":"Text","description":"The resolved question or search text."},"engine":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Engine","description":"The engine addressed, null when the target spans engines."},"named_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Named Count","description":"Answers naming the brand; null for searches or unmeasured questions."},"answer_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Answer Count","description":"Measured answers to this question, null for searches or unmeasured targets."},"answers_link":{"anyOf":[{"$ref":"#/components/schemas/AnswersLink"},{"type":"null"}],"description":"Answers supporting this target, null when no measured answers are available."}},"type":"object","required":["kind","uid","text","engine","named_count","answer_count","answers_link"],"title":"V1ActionTarget"},"V1Actions":{"properties":{"subject_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subject Label","description":"The subject's name: the prompt's text, the topic's name, the keyword, the figure, the domain or the competitor. Served when `subject` is sent; null when the brand has no such subject."},"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"suggestions_kept":{"type":"integer","title":"Suggestions Kept"},"suggestion_allowance":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Suggestion Allowance"},"actions":{"items":{"$ref":"#/components/schemas/V1Action"},"type":"array","title":"Actions"}},"type":"object","required":["meta","next_cursor","total","limit","offset","suggestions_kept","suggestion_allowance","actions"],"title":"V1Actions","examples":[{"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"total":1,"limit":20,"offset":0,"suggestions_kept":0,"suggestion_allowance":null,"actions":[{"waiting_since":null,"route":"content","demand":"Verified","first_citation":null,"citation_count":0,"write_language":null,"write_language_source":null,"write_language_locked":false,"placed_position":null,"not_seen_since_run":null,"evidence":null,"note":null,"id":"9a7b5c3d-1e2f-4a6b-8c0d-2e4f6a8b0c1d","title":"Publish a comparison page against Rival","detail":"Answers comparing agency CRMs cite Rival's page, not yours.","kind":"create_content","member":"writer","started_at":"2026-08-16T10:00:00Z","delivered_at":"2026-09-01T10:00:00Z","paid_off_at":"2026-09-08T10:00:00Z","preview":null,"group":"settled","scheduled_for":null,"holder":null,"stage":"verify","outcome":"verified_up","grounds":null,"done_when":null,"tracking":[],"gain":null,"focus":{"kind":"outside","id":null,"name":null},"kind_tag":null,"ending":null,"wait":null,"created_at":"2026-08-15T10:00:00Z","completed_at":"2026-09-01T10:00:00Z"}]}]},"V1AgainstBrand":{"properties":{"claims":{"items":{"$ref":"#/components/schemas/V1PageClaim"},"type":"array","title":"Claims"},"conflicts":{"items":{"$ref":"#/components/schemas/V1PageConflict"},"type":"array","title":"Conflicts","description":"The brief's claims the page's text contradicts, as the run read it."}},"type":"object","required":["claims","conflicts"],"title":"V1AgainstBrand"},"V1AiVisits":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"period":{"$ref":"#/components/schemas/V1Period"},"coverage":{"anyOf":[{"$ref":"#/components/schemas/V1VisitCoverage"},{"type":"null"}]},"pages":{"items":{"$ref":"#/components/schemas/V1PageAiVisits"},"type":"array","title":"Pages"}},"type":"object","required":["meta","next_cursor","total","limit","offset","period","coverage","pages"],"title":"V1AiVisits","examples":[{"coverage":null,"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"pages":[],"period":{"excluded_reports":0,"first_answer_at":null,"last_answer_at":null,"preset":"1w","reports":0},"total":0}]},"V1AnalystWeek":{"properties":{"answers_read":{"type":"integer","title":"Answers Read"},"pages_read":{"type":"integer","title":"Pages Read"},"actions_found":{"type":"integer","title":"Actions Found"},"competitors_tracked":{"type":"integer","title":"Competitors Tracked","description":"Competitors tracked now."},"competitors_checked_7d":{"type":"integer","title":"Competitors Checked 7D","description":"Distinct competitors checked in seven days."},"competitors_watched":{"type":"integer","title":"Competitors Watched","description":"Alias of competitors_checked_7d.","deprecated":true}},"type":"object","required":["answers_read","pages_read","actions_found","competitors_tracked","competitors_checked_7d","competitors_watched"],"title":"V1AnalystWeek"},"V1Answer":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"asked_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asked Language"},"language":{"type":"string","title":"Language","default":"unknown"},"id":{"type":"string","format":"uuid","title":"Id"},"prompt_id":{"type":"string","format":"uuid","title":"Prompt Id"},"prompt":{"type":"string","title":"Prompt"},"engine":{"type":"string","enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"title":"Engine"},"segment":{"type":"string","title":"Segment"},"read_at":{"type":"string","format":"date-time","title":"Read At"},"mentioned":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Mentioned"},"recommended":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Recommended"},"excerpt":{"type":"string","title":"Excerpt"},"states":{"$ref":"#/components/schemas/AnswerReadStates"},"segment_detail":{"anyOf":[{"$ref":"#/components/schemas/AnswerReadSegment"},{"type":"null"}]},"run_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Run Number"},"run_class":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Class"},"segment_config_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Segment Config Version"},"cited_page_count":{"type":"integer","title":"Cited Page Count","description":"Distinct pages cited by this answer.","default":0},"own_cited_page_count":{"type":"integer","title":"Own Cited Page Count","description":"Distinct owned pages cited by this answer.","default":0},"also_named":{"items":{"$ref":"#/components/schemas/NamedAnswerBrand"},"type":"array","title":"Also Named"},"text_retained":{"type":"boolean","title":"Text Retained","default":true},"excerpt_highlights":{"items":{"$ref":"#/components/schemas/AnswerHighlightSpan"},"type":"array","title":"Excerpt Highlights"},"text":{"type":"string","title":"Text"},"cited_urls":{"items":{"type":"string"},"type":"array","title":"Cited Urls"},"rivals_named":{"items":{"type":"string"},"type":"array","title":"Rivals Named"},"engine_vocabulary":{"items":{"$ref":"#/components/schemas/EngineVocabulary"},"type":"array","title":"Engine Vocabulary"},"cited_pages":{"items":{"$ref":"#/components/schemas/CitedPage"},"type":"array","title":"Cited Pages"},"subject_brand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subject Brand"},"rival_brands":{"items":{"type":"string"},"type":"array","title":"Rival Brands"},"highlights":{"items":{"$ref":"#/components/schemas/AnswerHighlightSpan"},"type":"array","title":"Highlights"}},"type":"object","required":["meta","asked_language","language","id","prompt_id","prompt","engine","segment","read_at","mentioned","recommended","excerpt","states","segment_detail","run_number","run_class","segment_config_version","cited_page_count","own_cited_page_count","also_named","text_retained","excerpt_highlights","text","cited_urls","rivals_named","engine_vocabulary","cited_pages","subject_brand","rival_brands","highlights"],"title":"V1Answer","examples":[{"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"asked_language":null,"language":"unknown","id":"5d2e8c1f-7a3b-4c6d-9e0f-1a2b3c4d5e6f","prompt_id":"0b8e5f7a-2c4d-4e6f-8a1b-3c5d7e9f1a2b","prompt":"best crm for agencies","engine":"openai","segment":"Agencies","read_at":"2026-09-22T09:00:00Z","mentioned":true,"recommended":true,"excerpt":"For agencies, Acme and Rival lead...","states":{"mentioned":null,"understood":null,"recommended":null,"praised":null,"icon_states":{"mentioned":"not_measured","understood":"not_measured","recommended":"not_measured","praised":"not_measured"}},"segment_detail":null,"run_number":null,"run_class":null,"segment_config_version":null,"cited_page_count":0,"own_cited_page_count":0,"also_named":[],"text_retained":true,"excerpt_highlights":[],"text":"For agencies, Acme and Rival lead the field.","cited_urls":["https://example.com/best-agency-crm"],"rivals_named":["Rival"],"engine_vocabulary":[],"cited_pages":[],"subject_brand":null,"rival_brands":[],"highlights":[]}]},"V1AnswerSummary":{"properties":{"asked_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asked Language"},"language":{"type":"string","title":"Language","default":"unknown"},"id":{"type":"string","format":"uuid","title":"Id"},"prompt_id":{"type":"string","format":"uuid","title":"Prompt Id"},"prompt":{"type":"string","title":"Prompt"},"engine":{"type":"string","enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"title":"Engine"},"segment":{"type":"string","title":"Segment"},"read_at":{"type":"string","format":"date-time","title":"Read At"},"mentioned":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Mentioned"},"recommended":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Recommended"},"excerpt":{"type":"string","title":"Excerpt"},"states":{"$ref":"#/components/schemas/AnswerReadStates"},"segment_detail":{"anyOf":[{"$ref":"#/components/schemas/AnswerReadSegment"},{"type":"null"}]},"run_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Run Number"},"run_class":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Class"},"segment_config_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Segment Config Version"},"cited_page_count":{"type":"integer","title":"Cited Page Count","description":"Distinct pages cited by this answer.","default":0},"own_cited_page_count":{"type":"integer","title":"Own Cited Page Count","description":"Distinct owned pages cited by this answer.","default":0},"also_named":{"items":{"$ref":"#/components/schemas/NamedAnswerBrand"},"type":"array","title":"Also Named"},"text_retained":{"type":"boolean","title":"Text Retained","default":true},"excerpt_highlights":{"items":{"$ref":"#/components/schemas/AnswerHighlightSpan"},"type":"array","title":"Excerpt Highlights"}},"type":"object","required":["asked_language","language","id","prompt_id","prompt","engine","segment","read_at","mentioned","recommended","excerpt","states","segment_detail","run_number","run_class","segment_config_version","cited_page_count","own_cited_page_count","also_named","text_retained","excerpt_highlights"],"title":"V1AnswerSummary"},"V1Answers":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"answers":{"items":{"$ref":"#/components/schemas/V1AnswerSummary"},"type":"array","title":"Answers"},"engine_vocabulary":{"items":{"$ref":"#/components/schemas/EngineVocabulary"},"type":"array","title":"Engine Vocabulary"},"period":{"anyOf":[{"$ref":"#/components/schemas/V1Period"},{"type":"null"}]},"has_more":{"type":"boolean","title":"Has More","default":false},"named_count":{"type":"integer","title":"Named Count","description":"Answers in the selection that name the brand.","default":0},"recommended_count":{"type":"integer","title":"Recommended Count","description":"Answers in the selection that recommend the brand.","default":0},"cited_page_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cited Page Key"}},"type":"object","required":["meta","next_cursor","total","limit","offset","answers","engine_vocabulary","period","has_more","named_count","recommended_count","cited_page_key"],"title":"V1Answers","examples":[{"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"total":1,"limit":20,"offset":0,"answers":[{"asked_language":null,"language":"unknown","id":"5d2e8c1f-7a3b-4c6d-9e0f-1a2b3c4d5e6f","prompt_id":"0b8e5f7a-2c4d-4e6f-8a1b-3c5d7e9f1a2b","prompt":"best crm for agencies","engine":"openai","segment":"Agencies","read_at":"2026-09-22T09:00:00Z","mentioned":true,"recommended":true,"excerpt":"For agencies, Acme and Rival lead...","states":{"mentioned":null,"understood":null,"recommended":null,"praised":null,"icon_states":{"mentioned":"not_measured","understood":"not_measured","recommended":"not_measured","praised":"not_measured"}},"segment_detail":null,"run_number":null,"run_class":null,"segment_config_version":null,"cited_page_count":0,"own_cited_page_count":0,"also_named":[],"text_retained":true,"excerpt_highlights":[]}],"engine_vocabulary":[],"period":null,"has_more":false,"named_count":0,"recommended_count":0,"cited_page_key":null}]},"V1ArtifactRecipient":{"properties":{"discovery":{"anyOf":[{"$ref":"#/components/schemas/RecipientDiscovery"},{"type":"null"}],"description":"The source lookup behind this recipient; null before classification or while a newer source read awaits this task's refresh."},"candidate":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Candidate","description":"A found contact awaiting your choice after a refusal."},"person":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Person"},"site_name":{"type":"string","title":"Site Name"},"found_in":{"anyOf":[{"type":"string","enum":["json_ld","author_meta","byline"]},{"type":"null"}],"title":"Found In"},"page_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Url"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address","description":"The address the email goes to; null while none is known."},"role":{"anyOf":[{"type":"string","enum":["editorial","commercial"]},{"type":"null"}],"title":"Role","description":"Whether the address reaches the site's editors or its commercial team; null when its role is unknown or a member gave the address."},"address_found_in":{"anyOf":[{"type":"string","enum":["author_page","contact_page","commercial_page","home_page","member"]},{"type":"null"}],"title":"Address Found In","description":"Where the address was found: the cited page that names its author, the site's contact, commercial or home page, or a member."},"address_page_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address Page Url","description":"The page the address was read from; null for a member's."},"generic":{"type":"boolean","title":"Generic","description":"Whether the address is a mailbox the site keeps for a role, such as editor@ or info@, rather than a person's.","default":false}},"type":"object","required":["discovery","candidate","person","site_name","found_in","page_url","address","role","address_found_in","address_page_url","generic"],"title":"V1ArtifactRecipient","description":"Who an outreach task is addressed to: a person, or the site's team where\n`person` is null, and which cited page named them; and the address its\nemail goes to, whom it reaches and where it was found."},"V1Asset":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The current asset identifier."},"action_id":{"type":"string","format":"uuid","title":"Action Id","description":"The work item that owns this asset."},"kind":{"type":"string","enum":["piece","draft","change","kit"],"title":"Kind","description":"The stored asset family."},"type":{"type":"string","title":"Type","description":"The format or artifact type used by the type filter."},"title":{"type":"string","title":"Title","description":"The piece title or the owning work title."},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version","description":"The current settled version, null for an unversioned change."},"state":{"anyOf":[{"type":"string","enum":["drafting","review","approved","live","stopped","failed"]},{"type":"string","enum":["ready","verifying"]}],"title":"State","description":"The lifecycle group used by the state filter."},"owner":{"anyOf":[{"$ref":"#/components/schemas/AssigneeResponse"},{"type":"null"}],"description":"The current eligible owner, null when unassigned or unavailable."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When this asset was last updated."},"opening":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Opening","description":"The first 400 characters of settled text, null before text is available."}},"type":"object","required":["id","action_id","kind","type","title","version","state","owner","updated_at","opening"],"title":"V1Asset"},"V1Assets":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"assets":{"items":{"$ref":"#/components/schemas/V1Asset"},"type":"array","title":"Assets","description":"Current assets on this page."},"total":{"type":"integer","title":"Total","description":"Current assets matching every filter before paging."},"limit":{"type":"integer","title":"Limit","description":"Maximum assets per page."},"offset":{"type":"integer","title":"Offset","description":"Assets skipped before this page."},"types":{"items":{"$ref":"#/components/schemas/AssetOption"},"type":"array","title":"Types","description":"Available asset types for this brand."},"states":{"items":{"$ref":"#/components/schemas/AssetOption"},"type":"array","title":"States","description":"Available lifecycle groups."},"owners":{"items":{"$ref":"#/components/schemas/AssigneeResponse"},"type":"array","title":"Owners","description":"Owners this caller may name for the brand."}},"type":"object","required":["meta","next_cursor","assets","total","limit","offset","types","states","owners"],"title":"V1Assets","examples":[{"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"assets":[],"total":0,"limit":20,"offset":0,"types":[],"states":[],"owners":[]}]},"V1AssistantRevenue":{"properties":{"revenue":{"type":"number","title":"Revenue","description":"Revenue in the read's currency, a minimum."},"orders":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Orders","description":"Purchases; null for a product, counted in units."},"key_events":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Key Events","description":"Key events; null for a product."},"visits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Visits","description":"Google Analytics sessions; null where it gives none for the cut."},"items":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Items","description":"Units bought; only for a product."},"average_order":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Order","description":"Revenue per order; null without orders."},"conversion":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Conversion","description":"Orders per visit in [0, 1]; null without a visit count."},"assistant":{"type":"string","title":"Assistant","description":"The AI assistant the purchases' visits came from."}},"type":"object","required":["revenue","orders","key_events","visits","items","average_order","conversion","assistant"],"title":"V1AssistantRevenue"},"V1AssistantVisits":{"properties":{"assistant":{"type":"string","title":"Assistant"},"sessions":{"type":"integer","title":"Sessions"}},"type":"object","required":["assistant","sessions"],"title":"V1AssistantVisits"},"V1Audit":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"state":{"type":"string","enum":["ready","awaiting_first_crawl"],"title":"State"},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headline","description":"Templated headline over the served page access and findings counts."},"page_types":{"items":{"type":"string"},"type":"array","title":"Page Types"},"crawler_hits_available":{"type":"boolean","title":"Crawler Hits Available"},"crawled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Crawled At"},"next_crawl_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Crawl At"},"readiness":{"anyOf":[{"$ref":"#/components/schemas/V1Readiness"},{"type":"null"}]},"checks_failing":{"type":"integer","title":"Checks Failing"},"checks_unmeasured":{"type":"integer","title":"Checks Unmeasured"},"groups":{"items":{"$ref":"#/components/schemas/V1AuditGroup"},"type":"array","title":"Groups"},"crawler_hits_days":{"type":"integer","title":"Crawler Hits Days"},"citations_scan":{"anyOf":[{"$ref":"#/components/schemas/DataAsOf"},{"type":"null"}],"description":"The last weekly scan, whose answers the pages' citations count."},"pages":{"items":{"$ref":"#/components/schemas/V1AuditPage"},"type":"array","title":"Pages"},"website":{"$ref":"#/components/schemas/V1BrandWebsite","description":"The Website score, findings and changes from the newest weekly read whose website read is decided, named in meta.data_as_of; pending with no figures before one."}},"type":"object","required":["meta","next_cursor","total","limit","offset","state","headline","page_types","crawler_hits_available","crawled_at","next_crawl_at","readiness","checks_failing","checks_unmeasured","groups","crawler_hits_days","citations_scan","pages","website"],"title":"V1Audit","description":"The latest crawl's site checks and pages. Audit has no period."},"V1AuditBrief":{"properties":{"brand_name":{"type":"string","title":"Brand Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"category":{"type":"string","title":"Category"},"target_buyer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Buyer"},"differentiator":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Differentiator"},"tone_formality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tone Formality"},"tone_complexity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tone Complexity"},"competitors":{"items":{"$ref":"#/components/schemas/V1BriefCompetitor"},"type":"array","title":"Competitors"},"questions":{"items":{"$ref":"#/components/schemas/V1BriefQuestion"},"type":"array","title":"Questions"}},"type":"object","required":["brand_name","description","category","target_buyer","differentiator","tone_formality","tone_complexity","competitors","questions"],"title":"V1AuditBrief","description":"What the scan was judged against, as confirmed."},"V1AuditCheck":{"properties":{"id":{"type":"string","title":"Id"},"label":{"type":"string","title":"Label"},"target":{"type":"string","title":"Target"},"measured":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Measured"},"met":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Met","description":"Null where the scan could not measure it."},"failing_pages":{"items":{"type":"string"},"type":"array","title":"Failing Pages","description":"Up to checks_limit pages the check fails, starting at failing_pages_offset."},"failing_pages_total":{"type":"integer","title":"Failing Pages Total","description":"All pages failing this check before paging."},"action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Action Id"},"failing_pages_offset":{"type":"integer","title":"Failing Pages Offset","default":0},"pages_in_scope":{"type":"integer","title":"Pages In Scope"}},"type":"object","required":["id","label","target","measured","met","failing_pages","failing_pages_total","action_id","failing_pages_offset","pages_in_scope"],"title":"V1AuditCheck"},"V1AuditGate":{"properties":{"key":{"type":"string","title":"Key"},"status":{"type":"string","enum":["pass","fail","unmeasured"],"title":"Status"}},"type":"object","required":["key","status"],"title":"V1AuditGate"},"V1AuditGroup":{"properties":{"name":{"type":"string","title":"Name"},"failing":{"type":"integer","title":"Failing"},"passing":{"type":"integer","title":"Passing"},"unmeasured":{"type":"integer","title":"Unmeasured"},"checks":{"items":{"$ref":"#/components/schemas/V1AuditCheck"},"type":"array","title":"Checks"},"checks_total":{"type":"integer","title":"Checks Total","description":"All checks in this audit group.","readOnly":true}},"type":"object","required":["name","failing","passing","unmeasured","checks","checks_total"],"title":"V1AuditGroup"},"V1AuditPage":{"properties":{"section":{"type":"string","title":"Section","description":"URL section, past a locale prefix.","default":"Site"},"finding_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Finding Ids","description":"Findings holding this page back; null where not measured."},"funnel":{"anyOf":[{"$ref":"#/components/schemas/PageFunnel"},{"type":"null"}],"description":"The page funnel on the pinned weekly window; null without a page id."},"path":{"type":"string","title":"Path"},"status_word":{"type":"string","title":"Status Word"},"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"page_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Page Id"},"page_type":{"type":"string","title":"Page Type"},"status":{"type":"string","enum":["readable","blocked_robots","noindex","does_not_load","needs_javascript","not_read"],"title":"Status"},"gates":{"items":{"$ref":"#/components/schemas/V1AuditGate"},"type":"array","title":"Gates"},"citations":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Citations","description":"Citations in the last weekly scan, citations_scan; null where that scan could not keep all its citations."},"crawler_hits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Crawler Hits","description":"Served crawler requests from the same frozen 28-day weekly scan window as page reads, ending two days before the scan started."},"read_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Read At"},"category":{"anyOf":[{"$ref":"#/components/schemas/AuditPageCategory"},{"type":"null"}],"description":"Where the page sits in the site's makeup, as the run categorised it."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"A code from facets.languages."},"findings":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Findings","description":"The findings holding the page back."},"worst":{"anyOf":[{"type":"string","enum":["issue","improve"]},{"type":"null"}],"title":"Worst","description":"The worst severity among them; null where there are none."},"claims_stated":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Claims Stated","description":"How many of claims_asked the page states; null where it was not asked."},"claims_asked":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Claims Asked","description":"The brief's claims (category, buyer, difference) asked of the page."},"change":{"anyOf":[{"type":"string","enum":["new","changed"]},{"type":"null"}],"title":"Change","description":"Found, or its content changed, since the previous weekly read."}},"type":"object","required":["section","finding_ids","funnel","path","status_word","url","title","page_id","page_type","status","gates","citations","crawler_hits","read_at","category","language","findings","worst","claims_stated","claims_asked","change"],"title":"V1AuditPage"},"V1AuditRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The Audit's id, as getScan reads it."},"state":{"type":"string","enum":["preparing","running","completed","failed","expired"],"title":"State","description":"preparing, running, completed or failed."},"domain":{"type":"string","title":"Domain","description":"The site the Audit read."},"started_at":{"type":"string","format":"date-time","title":"Started At","description":"When the Audit started."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When it completed; null until then."},"share_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Share Id","description":"The share link id of a delivered Audit, for /v1/scans/{share_id}/audit; null before delivery."},"progress_pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Progress Pct","description":"How far an Audit that is preparing or running has come; null once it completed or failed."},"failure_reason":{"anyOf":[{"type":"string","x-extensible-enum":["stuck_no_progress","brief_abandoned","insufficient_engine_signal","cost_cap_exceeded","report_inputs_missing","service_unavailable","other"]},{"type":"null"}],"title":"Failure Reason","description":"Why the scan failed, one of `stuck_no_progress`, `brief_abandoned`, `insufficient_engine_signal`, `cost_cap_exceeded`, `report_inputs_missing`, `service_unavailable` or `other`; null unless the scan failed. New values may be added."}},"type":"object","required":["id","state","domain","started_at","completed_at","share_id","progress_pct","failure_reason"],"title":"V1AuditRow"},"V1Audits":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total","description":"The Audits you ran."},"limit":{"type":"integer","title":"Limit","description":"The page size asked for."},"offset":{"type":"integer","title":"Offset","description":"Where this page starts."},"audits":{"items":{"$ref":"#/components/schemas/V1AuditRow"},"type":"array","title":"Audits","description":"Newest first."}},"type":"object","required":["meta","next_cursor","total","limit","offset","audits"],"title":"V1Audits","examples":[{"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"audits":[],"total":0}]},"V1AxisPane":{"properties":{"answers_link":{"anyOf":[{"$ref":"#/components/schemas/AnswersLink"},{"type":"null"}]},"axis":{"type":"string","title":"Axis"},"label":{"type":"string","title":"Label"},"questions":{"anyOf":[{"items":{"$ref":"#/components/schemas/AxisQuestion"},"type":"array"},{"type":"null"}],"title":"Questions","description":"One page of questions driving the selected figure, weakest first."},"questions_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Questions Total","description":"All questions driving this figure before paging."},"state":{"type":"string","title":"State","default":""},"measures":{"items":{"$ref":"#/components/schemas/Measure"},"type":"array","title":"Measures"},"trend":{"anyOf":[{"items":{"$ref":"#/components/schemas/PerceptionSeriesPoint"},"type":"array"},{"type":"null"}],"title":"Trend"},"by_engine":{"items":{"$ref":"#/components/schemas/EngineAxisRow"},"type":"array","title":"By Engine"},"by_intent":{"anyOf":[{"items":{"$ref":"#/components/schemas/IntentAxisRow"},"type":"array"},{"type":"null"}],"title":"By Intent"},"engines":{"items":{"$ref":"#/components/schemas/EngineScreen"},"type":"array","title":"Engines"},"intents":{"anyOf":[{"items":{"$ref":"#/components/schemas/IntentScreen"},"type":"array"},{"type":"null"}],"title":"Intents"},"recommended":{"anyOf":[{"$ref":"#/components/schemas/RecommendedPane"},{"type":"null"}]},"actions":{"items":{"$ref":"#/components/schemas/V1PaneAction"},"type":"array","title":"Actions"},"actions_total":{"type":"integer","title":"Actions Total","description":"Every live action about this subject, before the list is cut.","default":0},"next_step_action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Next Step Action Id","description":"The highest-priority live action that awaits a member and whose verb the reader may press; null when there is none."},"next_step":{"anyOf":[{"$ref":"#/components/schemas/V1PaneAction"},{"type":"null"}],"description":"The action `next_step_action_id` names, in the same shape as `actions`."},"figure":{"$ref":"#/components/schemas/V1Figure"},"parts":{"anyOf":[{"$ref":"#/components/schemas/AxisPaneParts"},{"type":"null"}],"description":"The AI-answer and web-page parts of a blended figure; null otherwise."},"tone_split":{"anyOf":[{"$ref":"#/components/schemas/ToneSplit"},{"type":"null"}]},"negative_quotes":{"items":{"$ref":"#/components/schemas/AxisQuote"},"type":"array","title":"Negative Quotes"},"claims":{"anyOf":[{"items":{"$ref":"#/components/schemas/ClaimRow"},"type":"array"},{"type":"null"}],"title":"Claims","description":"The bounded facts and brand claims measured in these answers."},"claims_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Claims Total","description":"All measured facts and claims before paging."},"best_quotes":{"anyOf":[{"items":{"$ref":"#/components/schemas/BestQuote"},"type":"array"},{"type":"null"}],"title":"Best Quotes","description":"The selected positive answer passages, each opening its stored answer."},"search":{"anyOf":[{"$ref":"#/components/schemas/V1SearchPaneDetail"},{"type":"null"}],"description":"Google detail when with_search_detail=true, with_panes=true and side=search, on Mentioned and Recommended. Omitted otherwise."},"brands":{"anyOf":[{"items":{"$ref":"#/components/schemas/V1SearchBrand"},"type":"array"},{"type":"null"}],"title":"Brands","description":"On Mentioned, Recommended and Praised with side=ai or side=all: the first five brands on the board, best first and unmeasured last, pinning you fifth if you place lower. Omitted otherwise."},"brands_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Brands Total","description":"With `brands`: the Competitors board's total, including unmeasured brands."},"paused_engines":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Paused Engines","description":"On every axis pane with side=ai or side=all: the engines paused for the latest report in the period, which answered nothing. Omitted otherwise."}},"type":"object","required":["answers_link","axis","label","state","measures","trend","by_engine","by_intent","engines","intents","recommended","actions","actions_total","next_step_action_id","next_step","figure","parts","tone_split","negative_quotes"],"title":"V1AxisPane"},"V1Baseline":{"properties":{"reports":{"type":"integer","title":"Reports"},"first_answer_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Answer At"},"last_answer_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Answer At"}},"type":"object","required":["reports","first_answer_at","last_answer_at"],"title":"V1Baseline"},"V1Brand":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"domain":{"type":"string","title":"Domain"},"name":{"type":"string","title":"Name"},"sells_to":{"type":"string","enum":["businesses","consumers"],"title":"Sells To","description":"Who the brand sells to: `businesses` or `consumers`."},"ecommerce":{"type":"boolean","title":"Ecommerce","description":"Whether the brand is measured as ecommerce, a brand selling goods online, which reads its products, sellers and prices."}},"type":"object","required":["id","domain","name","sells_to","ecommerce"],"title":"V1Brand"},"V1BrandProfile":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"brand_id":{"type":"string","format":"uuid","title":"Brand Id"},"name":{"type":"string","title":"Name"},"sells_to":{"type":"string","enum":["businesses","consumers"],"title":"Sells To","description":"Who the brand sells to: `businesses` or `consumers`."},"ecommerce":{"type":"boolean","title":"Ecommerce","description":"Whether the brand is measured as ecommerce, a brand selling goods online. An ecommerce brand has no customer size or service area."},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"target_buyer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Buyer"},"offering":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offering"},"differentiators":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Differentiators"},"customer_size":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"Customer Size"},"service_area":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"Service Area"},"use_cases":{"items":{"type":"string","maxLength":160,"minLength":1},"type":"array","maxItems":5,"title":"Use Cases"},"facts":{"items":{"$ref":"#/components/schemas/BrandFact"},"type":"array","title":"Facts"},"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market","description":"The Default segment's country or pooled market."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"subregion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subregion"},"domains":{"$ref":"#/components/schemas/OwnedDomainsDraft"}},"type":"object","required":["meta","brand_id","name","sells_to","ecommerce","aliases","category","target_buyer","offering","differentiators","customer_size","service_area","use_cases","facts","market","language","subregion","domains"],"title":"V1BrandProfile"},"V1BrandSnapshot":{"properties":{"share_id":{"type":"string","format":"uuid","title":"Share Id","description":"The Snapshot's report link id."},"measured_at":{"type":"string","format":"date-time","title":"Measured At","description":"When the Snapshot completed, in UTC."},"share_visibility":{"type":"string","enum":["public","restricted","revoked"],"title":"Share Visibility","description":"Public is unlisted, restricted needs member access, revoked cannot be shared."},"engines":{"items":{"type":"string"},"type":"array","title":"Engines","description":"Engines with measured answers in this Snapshot."},"total_engines":{"type":"integer","title":"Total Engines","description":"Number of engines asked by this Snapshot."},"answer_count":{"type":"integer","title":"Answer Count","description":"Measured answers in the Snapshot's issued figures."},"issued":{"anyOf":[{"$ref":"#/components/schemas/V1SnapshotFigures"},{"type":"null"}],"description":"The Snapshot's issued figures; null while partial or without an issued record."}},"type":"object","required":["share_id","measured_at","share_visibility","engines","total_engines","answer_count","issued"],"title":"V1BrandSnapshot"},"V1BrandSnapshots":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"snapshots":{"items":{"$ref":"#/components/schemas/V1BrandSnapshot"},"type":"array","title":"Snapshots","description":"Unlocked full Snapshots, newest first."}},"type":"object","required":["meta","snapshots"],"title":"V1BrandSnapshots"},"V1BrandWebsite":{"properties":{"state":{"type":"string","enum":["complete","pending","unavailable"],"title":"State","description":"complete, or pending or unavailable, which carry no figures."},"score":{"anyOf":[{"$ref":"#/components/schemas/V1WebsiteScore"},{"type":"null"}]},"groups":{"items":{"$ref":"#/components/schemas/V1WebsiteGroup"},"type":"array","title":"Groups"},"areas":{"items":{"$ref":"#/components/schemas/V1WebsiteArea"},"type":"array","title":"Areas"},"findings":{"items":{"$ref":"#/components/schemas/V1WebsiteFinding"},"type":"array","title":"Findings"},"fix_first":{"items":{"type":"string"},"type":"array","title":"Fix First","description":"Finding ids, the fix to make first leading."},"pages_with_findings":{"anyOf":[{"$ref":"#/components/schemas/V1PagesWithFindings"},{"type":"null"}]},"coverage":{"anyOf":[{"$ref":"#/components/schemas/V1WebsiteCoverage"},{"type":"null"}]},"versions":{"anyOf":[{"$ref":"#/components/schemas/V1WebsiteVersions"},{"type":"null"}]},"changes":{"anyOf":[{"$ref":"#/components/schemas/V1WebsiteChanges"},{"type":"null"}],"description":"Since the brand's previous weekly read; null on its first and on a scan."},"measured_more_deeply":{"type":"boolean","title":"Measured More Deeply","description":"The first weekly score after a Base or Full audit, which read the site more deeply."},"change":{"anyOf":[{"$ref":"#/components/schemas/FigureChange"},{"type":"null"}],"description":"Change since the previous comparable weekly score; null without one. Website scores are deterministic: low/high are null and real means a nonzero delta."},"series":{"items":{"$ref":"#/components/schemas/V1WebsiteSeriesPoint"},"type":"array","title":"Series","description":"Each weekly read, oldest first."},"next_read_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Read At"}},"type":"object","required":["state","score","groups","areas","findings","fix_first","pages_with_findings","coverage","versions","changes","measured_more_deeply","change","series","next_read_at"],"title":"V1BrandWebsite"},"V1Brands":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total","default":0},"limit":{"type":"integer","title":"Limit","default":100},"offset":{"type":"integer","title":"Offset","default":0},"brands":{"items":{"$ref":"#/components/schemas/V1Brand"},"type":"array","title":"Brands"}},"type":"object","required":["meta","next_cursor","total","limit","offset","brands"],"title":"V1Brands","examples":[{"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"total":0,"limit":100,"offset":0,"brands":[{"id":"6f1c2a4e-3b7d-4d2a-9c1e-8a5b0f3d2e71","domain":"acme.com","name":"Acme","sells_to":"businesses","ecommerce":false}]}]},"V1BriefCompetitor":{"properties":{"name":{"type":"string","title":"Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"}},"type":"object","required":["name","domain"],"title":"V1BriefCompetitor"},"V1BriefQuestion":{"properties":{"text":{"type":"string","title":"Text"},"page":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page","description":"The page the read matched it to; null where none."}},"type":"object","required":["text","page"],"title":"V1BriefQuestion"},"V1Change":{"properties":{"state":{"type":"string","enum":["up","down","steady","calibrating","first_report","not_comparable"],"title":"State","description":"The comparison state. A steady comparison is distinct from a first report, calibration or an incompatible baseline."},"delta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta","description":"The move in points: the shown value minus the baseline's, both as the trend draws them, or both over `compared_engines` where it names engines. Null when the baseline has no value."},"low":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Low","description":"The lower end of the paired test's 95% range for the move, in points."},"high":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"High","description":"The upper end of the paired test's 95% range for the move, in points."},"real":{"type":"boolean","title":"Real","description":"Whether the paired test over the prompt × engine cells both reads measured says the figure moved. The state is up or down only when this is true and the move has the sign of `delta`; otherwise it is steady and carries the signed `delta`."},"direction":{"type":"string","enum":["up","down","steady"],"title":"Direction"},"baseline":{"$ref":"#/components/schemas/V1Baseline"},"cells_unpaired":{"type":"integer","title":"Cells Unpaired"},"compared_engines":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Compared Engines","description":"The engines `delta` was sized on, when the baseline report asked other engines than the current period. The value and the trend still include every engine asked. Null when the size is the move the trend draws."}},"type":"object","required":["state","delta","low","high","real","direction","baseline","cells_unpaired","compared_engines"],"title":"V1Change"},"V1ChangeItem":{"properties":{"id":{"type":"string","title":"Id"},"source":{"type":"string","enum":["movement","insight","verification"],"title":"Source"},"kind":{"type":"string","title":"Kind"},"at":{"type":"string","format":"date-time","title":"At"},"target":{"$ref":"#/components/schemas/V1ChangeTarget"}},"type":"object","required":["id","source","kind","at","target"],"title":"V1ChangeItem"},"V1ChangeTarget":{"properties":{"route":{"type":"string","title":"Route"},"pane":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pane"},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key"},"filters":{"$ref":"#/components/schemas/ChangeFilters","description":"Engine, prompt and topic filters of the observation."}},"type":"object","required":["route","pane","key","filters"],"title":"V1ChangeTarget"},"V1Changes":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"since":{"type":"string","format":"date-time","title":"Since"},"writing":{"type":"boolean","title":"Writing"},"items":{"items":{"$ref":"#/components/schemas/V1ChangeItem"},"type":"array","title":"Items"}},"type":"object","required":["meta","next_cursor","total","limit","offset","since","writing","items"],"title":"V1Changes","examples":[{"items":[],"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"since":"2026-10-17T12:00:00Z","total":0,"writing":false}]},"V1Channel":{"properties":{"name":{"type":"string","title":"Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"mentioned":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentioned"},"answers":{"type":"integer","title":"Answers"},"prompts":{"type":"integer","title":"Prompts"}},"type":"object","required":["name","domain","mentioned","answers","prompts"],"title":"V1Channel"},"V1CitedPage":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"language":{"type":"string","title":"Language","default":"unknown"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"names":{"anyOf":[{"items":{"$ref":"#/components/schemas/SourcePageName"},"type":"array"},{"type":"null"}],"title":"Names"},"citation_evidence":{"type":"string","enum":["complete","partial","unavailable"],"title":"Citation Evidence","default":"complete"},"unavailable_scans":{"type":"integer","title":"Unavailable Scans","default":0},"period":{"$ref":"#/components/schemas/V1Period"},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id"},"document_key":{"type":"string","title":"Document Key"},"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"domain":{"type":"string","title":"Domain"},"ownership":{"type":"string","enum":["own","rival","independent"],"title":"Ownership"},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type"},"owner":{"type":"string","enum":["third_party","competitor","yours"],"title":"Owner"},"topic":{"anyOf":[{"$ref":"#/components/schemas/V1SourceTopic"},{"type":"null"}]},"prompt_count":{"type":"integer","title":"Prompt Count","description":"Prompts represented by this row under the selected filters."},"introduced_at_run":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Introduced At Run"},"citations":{"type":"integer","title":"Citations"},"answers":{"type":"integer","title":"Answers"},"names_you":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Names You"},"reports":{"items":{"$ref":"#/components/schemas/V1PageCitationReport"},"type":"array","title":"Reports"},"prompts":{"items":{"$ref":"#/components/schemas/V1PageCitingPrompt"},"type":"array","title":"Prompts"},"prompts_total":{"type":"integer","title":"Prompts Total","description":"All prompts matching this selection before paging."},"prompts_limit":{"type":"integer","title":"Prompts Limit"},"prompts_offset":{"type":"integer","title":"Prompts Offset"},"engines":{"items":{"$ref":"#/components/schemas/V1PageCitingEngine"},"type":"array","title":"Engines"},"answers_link":{"$ref":"#/components/schemas/V1PageAnswers"}},"type":"object","required":["meta","language","description","names","citation_evidence","unavailable_scans","period","document_id","document_key","url","title","domain","ownership","content_type","owner","topic","prompt_count","introduced_at_run","citations","answers","names_you","reports","prompts","prompts_total","prompts_limit","prompts_offset","engines","answers_link"],"title":"V1CitedPage"},"V1CitedPages":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"period":{"$ref":"#/components/schemas/V1Period"},"citation_evidence":{"type":"string","enum":["complete","partial","unavailable"],"title":"Citation Evidence","default":"complete"},"unavailable_scans":{"type":"integer","title":"Unavailable Scans","default":0},"sites_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sites Total","description":"All source sites under the selected filters."},"pages_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages Total","description":"All pages under the selected filters before paging."},"pages":{"items":{"$ref":"#/components/schemas/V1SourcePage"},"type":"array","title":"Pages"},"state":{"anyOf":[{"type":"string","enum":["ready","awaiting_first_scan","unavailable"]},{"type":"null"}],"title":"State"},"mix":{"items":{"$ref":"#/components/schemas/SourceMixSegment"},"type":"array","title":"Mix"}},"type":"object","required":["meta","next_cursor","total","limit","offset","period","citation_evidence","unavailable_scans","sites_total","pages_total","pages","state","mix"],"title":"V1CitedPages","examples":[{"citation_evidence":"complete","limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"mix":[],"next_cursor":null,"offset":0,"pages":[],"pages_total":null,"period":{"excluded_reports":0,"first_answer_at":null,"last_answer_at":null,"preset":"1w","reports":0},"sites_total":null,"state":null,"total":0,"unavailable_scans":0}]},"V1CitedSource":{"properties":{"domain":{"type":"string","title":"Domain"},"group":{"type":"string","enum":["own","rival","review","editorial","community","vendor","other"],"title":"Group"},"ownership":{"type":"string","enum":["own","rival","independent"],"title":"Ownership"},"citations":{"type":"integer","title":"Citations"},"citation_share_pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Citation Share Pct"},"read_pages_naming_you":{"type":"integer","title":"Read Pages Naming You"}},"type":"object","required":["domain","group","ownership","citations","citation_share_pct","read_pages_naming_you"],"title":"V1CitedSource","description":"A cited domain and its citations over the selected period."},"V1Commitment":{"properties":{"what":{"type":"string","title":"What","description":"What they said they will do."},"by":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"By","description":"When, where they gave a date."}},"type":"object","required":["what","by"],"title":"V1Commitment"},"V1Competitor":{"properties":{"product_cards":{"anyOf":[{"$ref":"#/components/schemas/BrandProductCards"},{"type":"null"}],"description":"Product-card figures for ecommerce brands; null for other brands and Google search."},"brand_key":{"type":"string","title":"Brand Key","description":"The key that opens this competitor's read."},"name":{"type":"string","title":"Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"is_you":{"type":"boolean","title":"Is You"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank","description":"The brand's place by Heralded Score on AI, or Mentioned in search on Google. Measured ties share a place; null for an unmeasured brand."},"heralded_score":{"$ref":"#/components/schemas/V1Figure"},"mentioned":{"$ref":"#/components/schemas/V1Figure"},"recommended":{"$ref":"#/components/schemas/V1Figure"},"share_of_voice_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Share Of Voice Pct"},"mentioned_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Mentioned Since","description":"Start of a shorter AI measurement population within the selected period."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"The latest stored AI description with with_details=true."},"most_said_for":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Most Said For","description":"The competitor's positive opinion with the most holders in the period, as its label. Null for you and where none is held. Filters do not narrow it."},"most_said_against":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Most Said Against","description":"The competitor's negative opinion with the most holders in the period, as its label. Null for you and where none is held."}},"type":"object","required":["product_cards","brand_key","name","domain","is_you","rank","heralded_score","mentioned","recommended","share_of_voice_pct","mentioned_since","description","most_said_for","most_said_against"],"title":"V1Competitor"},"V1CompetitorActivity":{"properties":{"week":{"type":"string","format":"date","title":"Week"},"new_pages":{"type":"integer","title":"New Pages"},"key_pages_changed":{"type":"integer","title":"Key Pages Changed"},"removed_pages":{"type":"integer","title":"Removed Pages"}},"type":"object","required":["week","new_pages","key_pages_changed","removed_pages"],"title":"V1CompetitorActivity"},"V1CompetitorCategory":{"properties":{"name":{"type":"string","title":"Name"},"group":{"type":"string","title":"Group"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["name","group","count"],"title":"V1CompetitorCategory"},"V1CompetitorDetail":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"product_cards":{"anyOf":[{"$ref":"#/components/schemas/BrandProductCards"},{"type":"null"}],"description":"Product-card figures for ecommerce brands; null for other brands and Google search."},"focus_selection":{"anyOf":[{"$ref":"#/components/schemas/Focus"},{"type":"null"}],"description":"The brand’s current focus selection and capacity."},"moves":{"anyOf":[{"$ref":"#/components/schemas/V1CompetitorSites"},{"type":"null"}],"description":"The first page of stored changes on this competitor’s site."},"period":{"$ref":"#/components/schemas/V1Period"},"brand_key":{"type":"string","title":"Brand Key"},"name":{"type":"string","title":"Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"is_tracked":{"type":"boolean","title":"Is Tracked"},"tracked_since":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Tracked Since"},"score":{"$ref":"#/components/schemas/ScoreMark"},"trend":{"$ref":"#/components/schemas/PromptTrend"},"history":{"items":{"$ref":"#/components/schemas/V1TrendPoint"},"type":"array","title":"History"},"versus":{"$ref":"#/components/schemas/Versus"},"figures":{"items":{"$ref":"#/components/schemas/Versus"},"type":"array","title":"Figures"},"lost":{"$ref":"#/components/schemas/VersusPage"},"won":{"$ref":"#/components/schemas/VersusPage"},"engines":{"items":{"$ref":"#/components/schemas/CompetitorEngine"},"type":"array","title":"Engines"},"paused_engines":{"items":{"type":"string"},"type":"array","title":"Paused Engines","description":"The engines paused for the latest report in the period, respecting the engine filter."},"pages":{"items":{"$ref":"#/components/schemas/CompetitorCitedPage"},"type":"array","title":"Pages","description":"The most cited rival pages. A floor unless citation_evidence is complete."},"pages_total":{"type":"integer","title":"Pages Total","description":"The number of cited rival pages. A floor unless citation_evidence is complete."},"citation_evidence":{"type":"string","enum":["complete","partial","unavailable"],"title":"Citation Evidence","default":"complete"},"unavailable_scans":{"type":"integer","title":"Unavailable Scans","default":0},"capacity":{"$ref":"#/components/schemas/RosterPool"},"answers_link":{"anyOf":[{"$ref":"#/components/schemas/AnswersLink"},{"type":"null"}]},"rival":{"anyOf":[{"$ref":"#/components/schemas/RivalPagePane"},{"type":"null"}]},"website":{"anyOf":[{"$ref":"#/components/schemas/V1CompetitorSiteDetail"},{"type":"null"}],"description":"Weekly site data and moves with with_details=true."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"The latest stored AI description."},"most_said_for":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Most Said For","description":"With details, the positive opinion with the most holders in the period."},"most_said_against":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Most Said Against","description":"With details, the negative opinion with the most holders in the period."},"description_scan_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Description Scan Id","description":"The report whose interpretation supplies the AI description."},"description_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Description At","description":"When the report supplying the AI description completed."},"work":{"items":{"$ref":"#/components/schemas/WorkRowResponse"},"type":"array","title":"Work","description":"One page of live work explicitly about this subject, highest priority first."},"actions_total":{"type":"integer","title":"Actions Total","description":"All live work items about this subject before paging.","default":0},"next_step":{"anyOf":[{"$ref":"#/components/schemas/WorkRowResponse"},{"type":"null"}],"description":"The highest-priority eligible work item across the subject’s entire live work selection, or null."},"figure_trends":{"additionalProperties":{"items":{"$ref":"#/components/schemas/FigurePoint"},"type":"array"},"type":"object","title":"Figure Trends","description":"Weekly competitor figure values, including your score less theirs under gap."},"figure_changes":{"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/FigureChange"},{"type":"null"}]},"type":"object","title":"Figure Changes","description":"Each competitor figure’s comparison with the earlier period."},"gap_delta":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Gap Delta","description":"Change in your score lead, yours less theirs; null when either comparison is unavailable or their baselines differ."}},"type":"object","required":["meta","product_cards","period","brand_key","name","domain","is_tracked","tracked_since","score","trend","history","versus","figures","lost","won","engines","paused_engines","pages","pages_total","citation_evidence","unavailable_scans","capacity","answers_link","rival","website","description","most_said_for","most_said_against","description_scan_id","description_at","work","actions_total","next_step","figure_trends","figure_changes","gap_delta"],"title":"V1CompetitorDetail"},"V1CompetitorKeyPage":{"properties":{"url":{"type":"string","title":"Url"},"kind":{"type":"string","enum":["homepage","pricing","key"],"title":"Kind"},"checked":{"type":"boolean","title":"Checked"},"changed":{"type":"boolean","title":"Changed"}},"type":"object","required":["url","kind","checked","changed"],"title":"V1CompetitorKeyPage"},"V1CompetitorPlan":{"properties":{"name":{"type":"string","title":"Name"},"price":{"type":"string","title":"Price"},"period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period"}},"type":"object","required":["name","price","period"],"title":"V1CompetitorPlan"},"V1CompetitorPricing":{"properties":{"state":{"type":"string","enum":["plans","not_readable","not_found"],"title":"State"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"plans":{"anyOf":[{"items":{"$ref":"#/components/schemas/V1CompetitorPlan"},"type":"array"},{"type":"null"}],"title":"Plans","description":"Prices as the page states them; null where pricing could not be read."}},"type":"object","required":["state","reason","url","plans"],"title":"V1CompetitorPricing"},"V1CompetitorRank":{"properties":{"position":{"type":"integer","title":"Position","description":"1 plus the tracked brands scoring higher; tied brands share a position."},"of":{"type":"integer","title":"Of","description":"The tracked brands with a score, you included."}},"type":"object","required":["position","of"],"title":"V1CompetitorRank","description":"Where the brand's Heralded Score places it among its tracked competitors."},"V1CompetitorSite":{"properties":{"key":{"type":"string","title":"Key"},"name":{"type":"string","title":"Name"},"host":{"type":"string","title":"Host"},"url":{"type":"string","title":"Url"},"screenshot_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Screenshot Url"},"above_the_fold":{"anyOf":[{"$ref":"#/components/schemas/V1AboveTheFold"},{"type":"null"}]},"proof":{"anyOf":[{"type":"string","enum":["yes","no","unclear"]},{"type":"null"}],"title":"Proof"},"sameness":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sameness","description":"Copy similarity, from 0 to 1."},"pricing":{"anyOf":[{"$ref":"#/components/schemas/V1CompetitorPricing"},{"type":"null"}]},"week":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Week"},"pages":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages"},"new":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"New"},"removed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Removed"},"key_pages_changed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Key Pages Changed"},"checks":{"anyOf":[{"additionalProperties":{"type":"boolean"},"type":"object"},{"type":"null"}],"title":"Checks"},"checks_met":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Checks Met"},"key_pages":{"items":{"$ref":"#/components/schemas/V1CompetitorKeyPage"},"type":"array","title":"Key Pages"},"categories":{"items":{"$ref":"#/components/schemas/V1CompetitorCategory"},"type":"array","title":"Categories"},"activity":{"items":{"$ref":"#/components/schemas/V1CompetitorActivity"},"type":"array","title":"Activity"},"unmeasured":{"additionalProperties":{"type":"string"},"type":"object","title":"Unmeasured"}},"type":"object","required":["key","name","host","url","screenshot_url","above_the_fold","proof","sameness","pricing","week","pages","new","removed","key_pages_changed","checks","checks_met","key_pages","categories","activity","unmeasured"],"title":"V1CompetitorSite"},"V1CompetitorSiteChange":{"properties":{"key":{"type":"string","title":"Key"},"name":{"type":"string","title":"Name"},"host":{"type":"string","title":"Host"},"url":{"type":"string","title":"Url"},"change":{"type":"string","enum":["new_page","removed_page","homepage_changed","pricing_changed","key_page_changed"],"title":"Change"},"week":{"type":"string","format":"date","title":"Week"},"observed_at":{"type":"string","format":"date-time","title":"Observed At"},"before":{"anyOf":[{"$ref":"#/components/schemas/V1CompetitorSiteSnapshot"},{"type":"null"}],"description":"The previous stored week's values, when available."},"after":{"anyOf":[{"$ref":"#/components/schemas/V1CompetitorSiteSnapshot"},{"type":"null"}],"description":"The changed week's stored values, when available."},"screenshot_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Screenshot Url","description":"The current homepage screenshot, never an earlier screenshot."},"insight":{"anyOf":[{"$ref":"#/components/schemas/ServedInsight"},{"type":"null"}],"description":"The work that fits the move, a comparison page against the competitor, and the work filed on it; null outside a brand's own read."}},"type":"object","required":["key","name","host","url","change","week","observed_at","before","after","screenshot_url","insight"],"title":"V1CompetitorSiteChange"},"V1CompetitorSiteDetail":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"state":{"type":"string","enum":["complete","pending","unavailable"],"title":"State"},"competitor":{"$ref":"#/components/schemas/V1CompetitorSite"},"changes":{"items":{"$ref":"#/components/schemas/V1CompetitorSiteChange"},"type":"array","title":"Changes","description":"The week's moves, one per competitor and type of change, each standing for its shallowest page; with `change`, each page of that type. A file, such as a PDF, is never a page."}},"type":"object","required":["meta","next_cursor","total","limit","offset","state","competitor","changes"],"title":"V1CompetitorSiteDetail"},"V1CompetitorSiteSnapshot":{"properties":{"week":{"type":"string","format":"date","title":"Week","description":"The detection week this stored reading describes."},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headline","description":"The stored homepage headline."},"checks":{"anyOf":[{"additionalProperties":{"type":"boolean"},"type":"object"},{"type":"null"}],"title":"Checks","description":"The stored homepage's offer, audience, reason and next-step checks."},"pricing":{"anyOf":[{"$ref":"#/components/schemas/V1CompetitorPricing"},{"type":"null"}],"description":"The stored pricing reading for this page."}},"type":"object","required":["week","headline","checks","pricing"],"title":"V1CompetitorSiteSnapshot"},"V1CompetitorSites":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"state":{"type":"string","enum":["complete","pending","unavailable"],"title":"State"},"reason":{"anyOf":[{"type":"string","enum":["no_read","read_running","read_failed"]},{"type":"null"}],"title":"Reason","description":"Why the read is incomplete; null when complete."},"rivals":{"items":{"$ref":"#/components/schemas/V1CompetitorSite"},"type":"array","title":"Rivals"},"changes":{"items":{"$ref":"#/components/schemas/V1CompetitorSiteChange"},"type":"array","title":"Changes","description":"The week's moves, one per competitor and type of change, each standing for its shallowest page; with `change`, each page of that type. A file, such as a PDF, is never a page."}},"type":"object","required":["meta","next_cursor","total","limit","offset","state","reason","rivals","changes"],"title":"V1CompetitorSites","examples":[{"changes":[],"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"reason":null,"rivals":[],"state":"complete","total":0}]},"V1Competitors":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"period":{"$ref":"#/components/schemas/V1Period"},"sides_available":{"items":{"type":"string","enum":["ai","search"]},"type":"array","title":"Sides Available","description":"The sides the period's reports observed: `ai`, and `search` once a report checked keywords. A read of reports without search observations states `[\"ai\"]`, and `all` is then the AI side."},"competitors":{"items":{"$ref":"#/components/schemas/V1Competitor"},"type":"array","title":"Competitors"},"discovered":{"items":{"$ref":"#/components/schemas/V1DiscoveredCompetitor"},"type":"array","title":"Discovered"},"channels":{"items":{"$ref":"#/components/schemas/V1Channel"},"type":"array","title":"Channels"},"share_of_voice":{"$ref":"#/components/schemas/V1ShareOfVoice"},"page":{"anyOf":[{"$ref":"#/components/schemas/CompetitorsPage"},{"type":"null"}]},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headline","description":"With details, the templated headline over the filtered leaderboard."},"sites":{"anyOf":[{"$ref":"#/components/schemas/V1CompetitorSites"},{"type":"null"}],"description":"Weekly site data and moves with with_details=true."},"description_scan_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Description Scan Id","description":"The report whose interpretation supplies the AI descriptions."},"description_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Description At","description":"When the report supplying the AI descriptions completed."}},"type":"object","required":["meta","next_cursor","period","sides_available","competitors","discovered","channels","share_of_voice","page","headline","sites","description_scan_id","description_at"],"title":"V1Competitors","examples":[{"channels":[],"competitors":[],"description_at":null,"description_scan_id":null,"discovered":[],"headline":null,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"page":null,"period":{"excluded_reports":0,"first_answer_at":null,"last_answer_at":null,"preset":"1w","reports":0},"share_of_voice":{"answers":0,"excluded_answers":0,"population":"all_answers","rows":[],"state":"measured"},"sides_available":[],"sites":null}]},"V1ConnectionInstance":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The connection instance's ID."},"account":{"type":"string","title":"Account","description":"The connected account's display name."},"owner":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner","description":"The owner's name, or their email address where they set no name; null for a connection without an owner."},"access":{"type":"string","enum":["personal","shared_brand","shared_workspace"],"title":"Access","description":"Personal, shared with the brand, or shared with the workspace."},"status":{"type":"string","enum":["connected","needs_property","degraded","reconnect_required","reauthorise","disconnected"],"title":"Status","description":"This instance's connection state."},"binding_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Binding Id","description":"This instance's binding to the brand, or null while unbound."},"in_use":{"type":"boolean","title":"In Use","description":"Whether a brand capability selects this instance. Always false for mail."}},"type":"object","required":["id","account","owner","access","status","binding_id","in_use"],"title":"V1ConnectionInstance"},"V1ConnectionStatus":{"properties":{"connect_another":{"type":"boolean","title":"Connect Another","description":"Whether this provider offers connecting another instance.","default":false},"provider":{"type":"string","title":"Provider"},"instances":{"items":{"$ref":"#/components/schemas/V1ConnectionInstance"},"type":"array","title":"Instances","description":"The provider's connection instances visible to this brand."},"binding_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Binding Id","description":"This brand's binding, matching an operation's subject.binding_id. Null for mail and when no selected binding exists."},"state":{"type":"string","enum":["connected","needs_property","degraded","reconnect_required","reauthorise","disconnected"],"title":"State"},"available":{"type":"boolean","title":"Available"},"reauthorise_from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reauthorise From"},"reauthorise_token_ended":{"type":"boolean","title":"Reauthorise Token Ended","default":true},"reconnect_account_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Reconnect Account Id","description":"While the state is `reauthorise`, the instance the brand's previous site held, which a reconnect for the new site names. Null in every other state and when the previous site held several instances."},"detail":{"additionalProperties":{"type":"string"},"type":"object","title":"Detail"},"notification_rules":{"additionalProperties":{"type":"boolean"},"type":"object","title":"Notification Rules"},"setup":{"$ref":"#/components/schemas/ConnectionSetupRow","description":"The connection's one status for the brand and its setup steps."},"last_activity":{"anyOf":[{"$ref":"#/components/schemas/ConnectionActivityRow"},{"type":"null"}],"description":"The newest thing the connection's account did, a sync, a send, a post or a health check. Null before it has done anything."},"status_fact":{"anyOf":[{"$ref":"#/components/schemas/ConnectionStatusFactRow"},{"type":"null"}],"description":"The connection status's dated activity, wait or problem."},"activity":{"items":{"$ref":"#/components/schemas/ConnectionActivityEventRow"},"type":"array","title":"Activity","description":"Up to five stored events, newest first."},"waiting_emails":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Waiting Emails","description":"A mailbox's approved emails still waiting to go, which switching or disconnecting it stops. Null for a connection that sends no email."}},"type":"object","required":["connect_another","provider","instances","binding_id","state","available","reauthorise_from","reauthorise_token_ended","reconnect_account_id","detail","notification_rules","setup","last_activity","status_fact","activity","waiting_emails"],"title":"V1ConnectionStatus"},"V1Conversation":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"messages":{"items":{"$ref":"#/components/schemas/V1ConversationMessage"},"type":"array","title":"Messages"},"has_older":{"type":"boolean","title":"Has Older"}},"type":"object","required":["meta","next_cursor","total","limit","offset","messages","has_older"],"title":"V1Conversation","examples":[{"has_older":false,"limit":20,"messages":[],"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"total":0}]},"V1ConversationMessage":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"member":{"type":"string","enum":["writer","publicist","engineer"],"title":"Member"},"author":{"type":"string","title":"Author"},"kind":{"type":"string","enum":["person","member","event","step"],"title":"Kind"},"body":{"type":"string","title":"Body"},"task_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Id"},"task_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Title"},"reply_to":{"anyOf":[{"$ref":"#/components/schemas/V1ConversationQuote"},{"type":"null"}]},"suggestions":{"items":{"$ref":"#/components/schemas/V1ConversationSuggestion"},"type":"array","title":"Suggestions"},"proposals":{"items":{"$ref":"#/components/schemas/V1ConversationProposal"},"type":"array","title":"Proposals","description":"Proposals without an action. Confirm and Not now stay in the app."},"mentions":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Mentions"},"answer_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Answer Status"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","member","author","kind","body","task_id","task_title","reply_to","suggestions","proposals","mentions","answer_status","created_at"],"title":"V1ConversationMessage"},"V1ConversationPage":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"messages":{"items":{"$ref":"#/components/schemas/V1StoredMessage"},"type":"array","title":"Messages"},"last_seq":{"type":"integer","title":"Last Seq"},"has_older":{"type":"boolean","title":"Has Older"},"has_newer":{"type":"boolean","title":"Has Newer"}},"type":"object","required":["meta","next_cursor","total","limit","offset","messages","last_seq","has_older","has_newer"],"title":"V1ConversationPage","examples":[{"has_newer":false,"has_older":false,"last_seq":0,"limit":20,"messages":[],"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"total":0}]},"V1ConversationProposal":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"kind":{"type":"string","title":"Kind","description":"Suggestion kind. New kinds may be added; handle unknown values gracefully.","x-extensible-enum":["start","not_now","schedule","request_changes","place_top","track_prompt","pause_prompt","add_competitor","remove_competitor","file_action","file_correction","file_page_fix","order_content"]},"label":{"type":"string","title":"Label"},"task_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Id"},"expected_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expected State"},"object":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Object"},"uses":{"items":{"type":"string"},"type":"array","title":"Uses"},"arguments":{"additionalProperties":true,"type":"object","title":"Arguments"},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result"},"hidden_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Hidden At"},"scheduled_for":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Scheduled For"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note"},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version"},"content_piece_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Content Piece Id"},"draft_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft Id"},"clicked_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Clicked By"},"clicked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Clicked At"}},"type":"object","required":["id","kind","label","task_id","expected_state","object","uses","arguments","result","hidden_at","scheduled_for","note","version","content_piece_id","draft_id","clicked_by","clicked_at"],"title":"V1ConversationProposal"},"V1ConversationQuote":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"author":{"type":"string","title":"Author"},"body":{"type":"string","title":"Body"}},"type":"object","required":["id","author","body"],"title":"V1ConversationQuote"},"V1ConversationSender":{"properties":{"state":{"type":"string","enum":["unset","mailbox","own_mail","unavailable"],"title":"State","description":"Where the conversation's emails go from once an email went or a member continued it from a sender: a mailbox, the member's own mail, or a mailbox no longer available. `unset` before then, while From is a member's choice or a suggestion.","default":"unset"},"account_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Account Id","description":"The mailbox connection the emails go from, pinned or suggested, retained after deletion; null for own mail and while no mailbox would send."},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address","description":"The address the emails go from, pinned or suggested, redacted for staff; null for own mail until a copy from it names the address, and while nothing would send."},"pinned":{"type":"boolean","title":"Pinned","description":"Whether a member, a continuation or a sent email chose the sender; false for the brand's suggested mailbox and while there is none.","default":false},"who_sends":{"type":"string","enum":["heralded","member"],"title":"Who Sends","description":"Who sends the emails: Heralded from the mailbox, or a member from their own mail.","default":"member"},"paused_reason":{"anyOf":[{"type":"string","enum":["made_personal","owner_left","disconnected","reconnect_required","alias_removed","owner_cannot_send"]},{"type":"null"}],"title":"Paused Reason","description":"Why the pinned sender can no longer send for the conversation; null while it can."},"paused_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paused At","description":"Always null: the pause is derived when read, not dated. Kept until the web stops reading it.","deprecated":true}},"type":"object","required":["state","account_id","address","pinned","who_sends","paused_reason","paused_at"],"title":"V1ConversationSender","description":"Who the conversation's emails go from (#9629): the sender pinned on it,\nor with none the mailbox the brand would use, who sends, and why a\npinned sender can no longer send."},"V1ConversationSuggestion":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"kind":{"type":"string","title":"Kind","description":"Suggestion kind. New kinds may be added; handle unknown values gracefully.","x-extensible-enum":["start","not_now","schedule","request_changes","place_top","track_prompt","pause_prompt","add_competitor","remove_competitor","file_action","file_correction","file_page_fix","order_content"]},"label":{"type":"string","title":"Label"},"task_id":{"type":"string","format":"uuid","title":"Task Id"},"expected_state":{"type":"string","title":"Expected State"},"object":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Object"},"uses":{"items":{"type":"string"},"type":"array","title":"Uses"},"arguments":{"additionalProperties":true,"type":"object","title":"Arguments"},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result"},"hidden_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Hidden At"},"scheduled_for":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Scheduled For"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note"},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version"},"content_piece_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Content Piece Id"},"draft_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft Id"},"clicked_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Clicked By"},"clicked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Clicked At"}},"type":"object","required":["id","kind","label","task_id","expected_state","object","uses","arguments","result","hidden_at","scheduled_for","note","version","content_piece_id","draft_id","clicked_by","clicked_at"],"title":"V1ConversationSuggestion"},"V1ConversationSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"agent":{"type":"string","title":"Agent"},"kind":{"type":"string","enum":["standing","chat"],"title":"Kind"},"owner_account_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Owner Account Id"},"shared":{"type":"boolean","title":"Shared"},"title":{"type":"string","title":"Title"},"archived":{"type":"boolean","title":"Archived"},"last_seq":{"type":"integer","title":"Last Seq"}},"type":"object","required":["id","agent","kind","owner_account_id","shared","title","archived","last_seq"],"title":"V1ConversationSummary"},"V1CopyAndProof":{"properties":{"specific":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Specific","description":"It backs its claims with specifics."},"sounds_generated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Sounds Generated","description":"It reads as generic filler."},"proof":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Proof","description":"It shows proof; null on an About page."}},"type":"object","required":["specific","sounds_generated","proof"],"title":"V1CopyAndProof"},"V1Correspondence":{"properties":{"sender":{"$ref":"#/components/schemas/V1ConversationSender","description":"The conversation's pinned sender and current pause reason."},"turn":{"type":"string","enum":["yours","theirs","closed"],"title":"Turn","description":"`theirs` while the task waits on the source, `yours` while a member's move, `closed` once the task settled."},"waiting_for":{"anyOf":[{"type":"string","enum":["reminder","quiet","asked","their_date","queued"]},{"type":"null"}],"title":"Waiting For","description":"What the task waits for: the next reminder's date, the quiet days after the last one, an answer to whether they replied, a date the source gave, or another task to the same contact closing."},"due_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Due On","description":"When that wait falls due."},"next_email":{"anyOf":[{"type":"string","x-extensible-enum":["first","answer","reminder_1","reminder_2","article"]},{"type":"null"}],"title":"Next Email","description":"The email of the brand's that goes next: the first email, an answer to theirs, a reminder, or the agreed article; null when none is due. Read an unknown value as another email of the brand's."},"approved":{"additionalProperties":{"type":"integer"},"type":"object","title":"Approved","description":"The emails approved to go and the draft version approved, by email. An email that arrives or an edit voids them."},"waiting_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Waiting Since","description":"When the brand's last email went."},"taken_over_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Taken Over At","description":"When a member took the emails over; Heralded writes no more of them."},"closed":{"anyOf":[{"type":"string","enum":["no_reply","no_reply_recorded","declined","opted_out","stopped"]},{"type":"null"}],"title":"Closed","description":"How the task closed, while it stays closed."},"closed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Closed At","description":"When the task closed, while it stays closed."},"reopened_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reopened At","description":"When an email arrived after the task closed unanswered and opened it."},"gaps":{"items":{"type":"string"},"type":"array","title":"Gaps","description":"What the email due next still needs from a member before it can go."},"reminders":{"items":{"$ref":"#/components/schemas/V1ActionDraft"},"type":"array","title":"Reminders","description":"The reminders approving the email due next approves with it, the newest draft of each; empty when none follows it or the text is withheld."},"thread_subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thread Subject","description":"The subject a reminder, an answer or the agreed article goes under, in the thread the first email started; null for the first email, whose subject opens its draft."},"emails":{"items":{"$ref":"#/components/schemas/V1Email"},"type":"array","title":"Emails","description":"The emails, oldest first."},"email_count":{"type":"integer","title":"Email Count","description":"All emails on the task."},"goal":{"type":"string","enum":["named","correction","co_marketing"],"title":"Goal","description":"What the task is for: to be named on the source, to have a claim corrected, or to agree co-marketing.","default":"named"},"offers":{"items":{"$ref":"#/components/schemas/V1Offer"},"type":"array","title":"Offers","description":"The terms on the table, every version oldest first; empty when withheld."},"requests":{"items":{"$ref":"#/components/schemas/V1ReadRequest"},"type":"array","title":"Requests","description":"What they asked of the brand that is still open; empty when withheld."},"awaiting":{"anyOf":[{"$ref":"#/components/schemas/V1Commitment"},{"type":"null"}],"description":"What they agreed to do, which the task waits for."},"away_until":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Away Until","description":"When they said they are back."},"published_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published Url","description":"Where they said the work is live, on their own site."},"our_deadline":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Our Deadline","description":"The date they need something still owed from the brand by."},"asks_member":{"type":"boolean","title":"Asks Member","description":"They agreed to co-marketing that only a member can say is live: the task completes on a member's word.","default":false},"article":{"anyOf":[{"$ref":"#/components/schemas/V1CorrespondenceArticle"},{"type":"null"}],"description":"The article the agreement needs, once a member agreed and chose who writes it; null otherwise."},"published_check":{"anyOf":[{"type":"string","x-extensible-enum":["pending","named","not_named","unreadable"]},{"type":"null"}],"title":"Published Check","description":"What Heralded's read of `published_url` found: still to read, the page names the brand, it is live without naming the brand, or it could not be read."},"state":{"anyOf":[{"$ref":"#/components/schemas/ConversationState"},{"type":"null"}],"description":"Where the conversation stands, served so no client works it out: whose move it is, the email due next and who sends it, the wait, the step, the recipient and what each side owes. Work rows read the same whose move, wait and step."},"mailbox":{"anyOf":[{"$ref":"#/components/schemas/V1Mailbox"},{"type":"null"}],"description":"The mailbox of this task's sender, with its scheduled send; null where they go from the member's own mail."}},"type":"object","required":["sender","turn","waiting_for","due_on","next_email","approved","waiting_since","taken_over_at","closed","closed_at","reopened_at","gaps","reminders","thread_subject","emails","email_count","goal","offers","requests","awaiting","away_until","published_url","our_deadline","asks_member","article","published_check","state","mailbox"],"title":"V1Correspondence","description":"The emails of a task with a source and whose move it is."},"V1CorrespondenceArticle":{"properties":{"by":{"type":"string","enum":["heralded","member"],"title":"By","description":"Who writes it: Heralded, as a piece in Studio, or the brand itself."},"stage":{"type":"string","enum":["member","writing","review","approved","failed","sent"],"title":"Stage","description":"Where it stands: the brand writing it, Heralded writing it or a revision of it, waiting for review, approved to go, failed, or sent with no change owed. Read an unknown value as writing."},"action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Action Id","description":"The content action the article is when Heralded writes it: its piece is this task's asset, and it is never a row of its own in Work."},"piece_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Piece Id","description":"The article's piece, once ordered from the writer."},"credits":{"type":"integer","title":"Credits","description":"The content credits ordering it took.","default":0},"requirements":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Requirements","description":"What they asked of the article, in one line."},"deadline":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Deadline","description":"When they need it by."},"sent_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sent Version","description":"The piece version that last went to them."},"sent_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Sent At","description":"When it last went."},"revision_requested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revision Requested At","description":"When they asked for changes to the article they were sent, while the revision has not gone."}},"type":"object","required":["by","stage","action_id","piece_id","credits","requirements","deadline","sent_version","sent_at","revision_requested_at"],"title":"V1CorrespondenceArticle","description":"The article an agreement on a task with a source needs (#9353)."},"V1Count":{"properties":{"count":{"type":"integer","title":"Count"},"of":{"type":"integer","title":"Of"},"pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pct"}},"type":"object","required":["count","of","pct"],"title":"V1Count","description":"A count, what it is out of, and its share in points: null where it is out\nof nothing."},"V1CrawlerBot":{"properties":{"bot":{"type":"string","title":"Bot"},"operator":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operator"},"hits":{"type":"integer","title":"Hits"},"category":{"anyOf":[{"type":"string","enum":["training","ai_search","user_fetch","search_engine"]},{"type":"null"}],"title":"Category"}},"type":"object","required":["bot","operator","hits","category"],"title":"V1CrawlerBot"},"V1Design":{"properties":{"hierarchy":{"$ref":"#/components/schemas/V1ScreenCheck"},"clutter":{"$ref":"#/components/schemas/V1ScreenCheck"},"readability":{"$ref":"#/components/schemas/V1ScreenCheck"},"looks_current":{"$ref":"#/components/schemas/V1ScreenCheck"},"fits_buyer":{"$ref":"#/components/schemas/V1ScreenCheck"},"generated_look":{"$ref":"#/components/schemas/V1ScreenCheck"}},"type":"object","required":["hierarchy","clutter","readability","looks_current","fits_buyer","generated_look"],"title":"V1Design"},"V1Diagnosis":{"properties":{"rival_gaps":{"$ref":"#/components/schemas/V1RivalGaps"},"rival_sources":{"$ref":"#/components/schemas/V1RivalSources"},"drafts":{"$ref":"#/components/schemas/V1DiagnosisDrafts"}},"type":"object","required":["rival_gaps","rival_sources","drafts"],"title":"V1Diagnosis","description":"What rivals win over the last week, and the drafts ready to answer it."},"V1DiagnosisDrafts":{"properties":{"ready":{"type":"integer","title":"Ready","description":"Open work whose draft or planned change waits on review."},"draftable":{"type":"integer","title":"Draftable","description":"Open work Heralded can draft now."}},"type":"object","required":["ready","draftable"],"title":"V1DiagnosisDrafts"},"V1DiscoveredCompetitor":{"properties":{"name":{"type":"string","title":"Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value"},"low":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Low"},"high":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"High"},"answers":{"type":"integer","title":"Answers"},"state":{"type":"string","title":"State","x-extensible-enum":["measured","too_few_answers","calibrating","first_report","not_comparable","not_measured","pending","not_scored"]}},"type":"object","required":["name","domain","value","low","high","answers","state"],"title":"V1DiscoveredCompetitor"},"V1Email":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The email's identifier."},"direction":{"type":"string","enum":["in","out"],"title":"Direction","description":"`out` for an email of the brand's, `in` for one from the source."},"arrived_by":{"type":"string","title":"Arrived By","description":"How Heralded learned of it: `marked_sent` when a member marked the approved email sent, `pasted` for a reply a member pasted, `noted` for a reply a member said came without its text, `member_reply` for an email a member wrote from their own mail, `bcc` for a sent copy, `forwarded` for a forwarded reply, and `mailbox` for an email sent or synced through the brand's connected mailbox. Read an unknown value as another way it arrived.","x-extensible-enum":["marked_sent","pasted","noted","member_reply","bcc","forwarded","mailbox"]},"occurred_at":{"type":"string","format":"date-time","title":"Occurred At","description":"When it was sent or received."},"email":{"anyOf":[{"type":"string","x-extensible-enum":["first","answer","reminder_1","reminder_2","article"]},{"type":"null"}],"title":"Email","description":"Which approved email of the brand's this was: the first email, an answer to theirs, a reminder after either, or the agreed article; null for any other. Read an unknown value as another email of the brand's."},"subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subject","description":"Its subject; null when unknown or withheld."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text","description":"Its text; null when unknown or withheld."},"new_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"New Text","description":"The sender's new words without quoted mail; null when the split is uncertain or the text is withheld."},"body_format":{"type":"string","enum":["plain","markdown"],"title":"Body Format","description":"How to render the text: markdown for Heralded-composed mail, plain for other mail.","default":"plain"},"party_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Party Name","description":"The served contact name, mail display name or address; null when withheld."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Its language code; null when unknown or withheld."},"english_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"English Text","description":"Stored English text, where translated; null when withheld."},"sender":{"anyOf":[{"$ref":"#/components/schemas/V1EmailParty"},{"type":"null"}],"description":"Who it is from; null when withheld."},"recipients":{"items":{"$ref":"#/components/schemas/V1EmailParty"},"type":"array","title":"Recipients","description":"Who it went to; empty when withheld."},"attachments":{"items":{"$ref":"#/components/schemas/V1MailAttachment"},"type":"array","title":"Attachments","description":"Attachment names and byte sizes; empty when withheld."},"reading":{"anyOf":[{"$ref":"#/components/schemas/V1EmailReading"},{"type":"null"}],"description":"What Heralded read in an email of theirs; null for an email of the brand's, one that came without its text, and when withheld."}},"type":"object","required":["id","direction","arrived_by","occurred_at","email","subject","text","new_text","body_format","party_name","language","english_text","sender","recipients","attachments","reading"],"title":"V1Email","description":"One email on a task with a source, either way (#9344)."},"V1EmailParty":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"The name the email carries, if any."},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address","description":"The email address, where known."}},"type":"object","required":["name","address"],"title":"V1EmailParty"},"V1EmailReading":{"properties":{"state":{"type":"string","enum":["pending","read","unread"],"title":"State","description":"`pending` while Heralded reads it, `read` once read, `unread` when it could not be read: then nothing on the task changed because of it."},"said":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Said","description":"One sentence of what they said."},"answer":{"anyOf":[{"type":"string","enum":["yes","no","already","conditional","none"]},{"type":"null"}],"title":"Answer","description":"How they answered what the brand asked: agreed, refused, already done, agreed on a condition or a price, or did not answer it."},"automatic":{"type":"boolean","title":"Automatic","description":"An automatic reply, such as an away notice: not a reply.","default":false},"opt_out":{"type":"boolean","title":"Opt Out","description":"They asked not to be contacted again.","default":false},"agreed":{"type":"boolean","title":"Agreed","description":"They agreed to what the brand asked.","default":false},"asks_payment":{"type":"boolean","title":"Asks Payment","description":"They asked to be paid.","default":false},"requests":{"items":{"$ref":"#/components/schemas/V1ReadRequest"},"type":"array","title":"Requests","description":"What they asked of the brand."},"commitment":{"anyOf":[{"$ref":"#/components/schemas/V1Commitment"},{"type":"null"}],"description":"What they said they will do."},"away_until":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Away Until","description":"When they are back."},"contact":{"anyOf":[{"$ref":"#/components/schemas/V1EmailParty"},{"type":"null"}],"description":"Another person they said to write to."},"published_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published Url","description":"Where they said the brand's mention or piece is live."}},"type":"object","required":["state","said","answer","automatic","opt_out","agreed","asks_payment","requests","commitment","away_until","contact","published_url"],"title":"V1EmailReading","description":"What Heralded read in an email of theirs (#9345)."},"V1EmailSend":{"properties":{"state":{"type":"string","enum":["scheduled","sending","unresolved"],"title":"State","description":"`scheduled` while it waits for its moment and can still be undone, `sending` while it goes, `unresolved` when Heralded could not confirm it went: a member checks the mailbox's sent mail and settles it, and the task waits."},"scheduled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Scheduled At","description":"When it goes: a weekday between 09:00 and 17:00 in the mailbox's time zone."},"daily_limit":{"type":"boolean","title":"Daily Limit","description":"Whether the mailbox's emails for the day were booked, so it goes on a later day."},"sender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sender","description":"The mailbox it leaves, or left, from: the one it was approved through, whose sent mail an unconfirmed send is checked in, even after the brand's mailboxes changed."},"from_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From Address","description":"The address the email goes from, fixed when it was approved: the mailbox's own address or one of its aliases. `sender` stays the mailbox whose sent mail holds it. Null for an email approved before it was recorded."},"email":{"anyOf":[{"type":"string","x-extensible-enum":["first","reminder_1","reminder_2","article"]},{"type":"null"}],"title":"Email","description":"Which email it carries: the first email or an answer (`first`), a follow-up, or the agreed article. A retry of an email that was not delivered names the email it sends again. Read an unknown value as another email of the brand's."},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version","description":"The draft version it carries, the one approved; the piece version for the article."}},"type":"object","required":["state","scheduled_at","daily_limit","sender","from_address","email","version"],"title":"V1EmailSend","description":"An approved email on its way from its conversation's mailbox (#9349)."},"V1EnginePane":{"properties":{"engine_id":{"type":"string","title":"Engine Id"},"display_name":{"type":"string","title":"Display Name"},"figures":{"$ref":"#/components/schemas/Figures"},"score":{"$ref":"#/components/schemas/ScoreMark"},"marks":{"items":{"$ref":"#/components/schemas/ScoreMark"},"type":"array","title":"Marks"},"change":{"$ref":"#/components/schemas/PromptTrend"},"answers":{"type":"integer","title":"Answers"},"prompts":{"type":"integer","title":"Prompts"},"period":{"$ref":"#/components/schemas/PeriodDescriptor"},"filters":{"$ref":"#/components/schemas/FigureFilters"},"score_trend":{"items":{"$ref":"#/components/schemas/FigurePoint"},"type":"array","title":"Score Trend"},"tiles":{"items":{"$ref":"#/components/schemas/PromptTile"},"type":"array","title":"Tiles"},"competitors":{"items":{"$ref":"#/components/schemas/PromptCompetitor"},"type":"array","title":"Competitors"},"competitors_total":{"type":"integer","title":"Competitors Total","description":"All competitors under the engine's selected filters before paging."},"competitors_limit":{"type":"integer","title":"Competitors Limit"},"competitors_offset":{"type":"integer","title":"Competitors Offset"},"strongest_prompts":{"items":{"$ref":"#/components/schemas/EnginePrompt"},"type":"array","title":"Strongest Prompts"},"weakest_prompts":{"items":{"$ref":"#/components/schemas/EnginePrompt"},"type":"array","title":"Weakest Prompts"},"topic_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topic Label","description":"The selected topic’s current display name; null when no tracked topic is selected."},"questions_total":{"type":"integer","title":"Questions Total","description":"All questions under the selected filters before paging.","default":0},"questions_limit":{"type":"integer","title":"Questions Limit","description":"Maximum questions returned for the selected weakest or strongest section.","default":3},"questions_offset":{"type":"integer","title":"Questions Offset","description":"Questions skipped in the selected weakest or strongest section.","default":0},"sources":{"items":{"$ref":"#/components/schemas/V1EngineSource"},"type":"array","title":"Sources"},"sources_total":{"type":"integer","title":"Sources Total","description":"All cited sources under the selected filters before paging.","default":0},"sources_limit":{"type":"integer","title":"Sources Limit","description":"Maximum cited sources returned in this page.","default":5},"sources_offset":{"type":"integer","title":"Sources Offset","description":"Cited sources skipped before this page.","default":0},"work":{"items":{"$ref":"#/components/schemas/WorkRowResponse"},"type":"array","title":"Work","description":"One page of live work explicitly about this subject, highest priority first."},"actions_total":{"type":"integer","title":"Actions Total","description":"All live work items about this subject before paging.","default":0},"next_step":{"anyOf":[{"$ref":"#/components/schemas/WorkRowResponse"},{"type":"null"}],"description":"The highest-priority eligible work item across the subject’s entire live work selection, or null."}},"type":"object","required":["engine_id","display_name","figures","score","marks","change","answers","prompts","period","filters","score_trend","tiles","competitors","competitors_total","competitors_limit","competitors_offset","strongest_prompts","weakest_prompts","topic_label","questions_total","questions_limit","questions_offset","sources","sources_total","sources_limit","sources_offset","work","actions_total","next_step"],"title":"V1EnginePane"},"V1EngineSource":{"properties":{"source_type":{"anyOf":[{"type":"string","enum":["industry_authority","review","regulatory","media","educational","community","consulting","social","vendor","directory","unclassified"]},{"type":"string","const":"corporate"}],"title":"Source Type","description":"The site's type, using the Sources vocabulary."},"owner":{"type":"string","enum":["third_party","competitor","yours"],"title":"Owner","description":"Whether the site is yours, a competitor's or third-party."},"domain":{"type":"string","title":"Domain"},"group":{"type":"string","enum":["own","rival","review","editorial","community","vendor","other"],"title":"Group"},"ownership":{"type":"string","enum":["own","rival","independent"],"title":"Ownership"},"citations":{"type":"integer","title":"Citations"},"citation_share_pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Citation Share Pct"},"read_pages_naming_you":{"type":"integer","title":"Read Pages Naming You"},"names_you":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Names You"}},"type":"object","required":["source_type","owner","domain","group","ownership","citations","citation_share_pct","read_pages_naming_you","names_you"],"title":"V1EngineSource"},"V1Evidence":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"scan_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Scan Id"},"run_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Run Number"},"items":{"items":{"$ref":"#/components/schemas/V1EvidenceItem"},"type":"array","title":"Items"}},"type":"object","required":["meta","next_cursor","total","limit","offset","scan_id","run_number","items"],"title":"V1Evidence","examples":[{"items":[],"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"run_number":null,"scan_id":null,"total":0}]},"V1EvidenceItem":{"properties":{"id":{"type":"string","title":"Id"},"module":{"type":"string","title":"Module"},"kind":{"type":"string","title":"Kind"},"target":{"type":"string","title":"Target"},"segment":{"type":"string","title":"Segment"},"fact":{"type":"string","title":"Fact"},"observed_at":{"type":"string","format":"date-time","title":"Observed At"},"plays":{"items":{"type":"string"},"type":"array","title":"Plays"},"prompt_uids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Prompt Uids","description":"Stable ids of the prompts this evidence supports; empty when none are linked."}},"type":"object","required":["id","module","kind","target","segment","fact","observed_at","plays","prompt_uids"],"title":"V1EvidenceItem"},"V1FactOrigins":{"properties":{"probe":{"$ref":"#/components/schemas/V1PerceptionVerdicts","description":"Answers to the fact's own question, asked once per engine each week."},"prompt":{"$ref":"#/components/schemas/V1PerceptionVerdicts","description":"Answers to tracked prompts that name the brand."}},"type":"object","required":["probe","prompt"],"title":"V1FactOrigins","description":"A fact's verdict counts by where the answers came from."},"V1Figure":{"properties":{"basis":{"type":"string","enum":["ai","ai_and_web","search"],"title":"Basis","description":"Evidence used by this figure.","default":"ai"},"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value"},"low":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Low"},"high":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"High"},"numerator":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Numerator","description":"The figure numerator; null for a blended score."},"denominator":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Denominator","description":"The figure denominator; null for a blended score."},"answers":{"type":"integer","title":"Answers"},"state":{"type":"string","title":"State","description":"pending means Search is awaiting its first measurement, with a null value. not_measured means no measurement is available. not_scored means the figure is intentionally not scored, even when its underlying shares are measured. These states have null values and never mean zero. New states may be added; handle unknown values gracefully.","x-extensible-enum":["measured","too_few_answers","calibrating","first_report","not_comparable","not_measured","pending","not_scored"]},"change":{"anyOf":[{"$ref":"#/components/schemas/V1Change"},{"type":"null"}]},"trend":{"items":{"$ref":"#/components/schemas/V1TrendPoint"},"type":"array","title":"Trend"}},"type":"object","required":["basis","value","low","high","numerator","denominator","answers","state","change","trend"],"title":"V1Figure"},"V1GoogleRank":{"properties":{"state":{"type":"string","enum":["ranked","not_in_top_20","pending","failed","unmeasured"],"title":"State","description":"Rank from a successful Google read within seven days in the market of the answer that searched it. not_in_top_20 requires a successful read at least twenty results deep. A recent usable success still stands while another read is pending or failed; otherwise pending and failed describe the latest attempt. Without a usable recent read or current attempt, the state is unmeasured."},"position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Position","description":"The brand's best Google position, 1 to 20."},"read_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Read Id","description":"The Google read behind this state."},"checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Checked At","description":"When Google results were fetched."},"failure_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failure Reason"}},"type":"object","required":["state","position","read_id","checked_at","failure_reason"],"title":"V1GoogleRank"},"V1GoogleShopping":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total","description":"Rows of this list under these filters, before paging."},"limit":{"type":"integer","title":"Limit","description":"The page's maximum rows."},"offset":{"type":"integer","title":"Offset","description":"Rows skipped before this page."},"period":{"$ref":"#/components/schemas/V1Period","description":"The weekly reports the searches come from."},"state":{"anyOf":[{"type":"string","enum":["complete","partial","unavailable","pending"]},{"type":"null"}],"title":"State","description":"Whether every search was read; null where none was asked."},"scan_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Scan Id","description":"The report whose searches these are."},"searches":{"items":{"$ref":"#/components/schemas/ShoppingSearch"},"type":"array","title":"Searches","description":"One page of searches."}},"type":"object","required":["meta","next_cursor","total","limit","offset","period","state","scan_id","searches"],"title":"V1GoogleShopping","description":"Your best Google Shopping position for each search the newest report read.","examples":[{"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"total":0,"limit":20,"offset":0,"period":{"preset":"1w","reports":1,"first_answer_at":null,"last_answer_at":null,"excluded_reports":0},"state":null,"scan_id":null,"searches":[]}]},"V1Headline":{"properties":{},"type":"object","title":"V1Headline"},"V1InsightLink":{"properties":{"kind":{"type":"string","title":"Kind"},"run_number":{"type":"integer","title":"Run Number"},"change":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}],"title":"Change","description":"The priority inputs this scan changed, each `{from, to}`."},"statement":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Statement","description":"The finding's statement; null once its evidence is deleted."},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["kind","run_number","change","statement","created_at"],"title":"V1InsightLink","description":"One scan that created or reprioritised the action."},"V1IssuedRate":{"properties":{"value":{"type":"integer","title":"Value"},"low":{"type":"integer","title":"Low"},"high":{"type":"integer","title":"High"},"k":{"type":"integer","title":"K","description":"The answers that counted."},"n":{"type":"integer","title":"N","description":"The answers read."},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank","description":"The brand's place among the rivals this scan scored; null where no answer counted the brand."},"rank_of":{"type":"integer","title":"Rank Of","description":"The brand and every rival measured."}},"type":"object","required":["value","low","high","k","n","rank","rank_of"],"title":"V1IssuedRate"},"V1IssuedScore":{"properties":{"value":{"type":"integer","title":"Value"},"low":{"type":"integer","title":"Low"},"high":{"type":"integer","title":"High"},"band":{"type":"string","title":"Band"},"answers":{"type":"integer","title":"Answers"}},"type":"object","required":["value","low","high","band","answers"],"title":"V1IssuedScore"},"V1KeyPage":{"properties":{"url":{"type":"string","title":"Url"},"path":{"type":"string","title":"Path","description":"Pass it, without its leading slash, to read this page alone."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"above_the_fold":{"$ref":"#/components/schemas/V1AboveTheFold"},"moves":{"items":{"$ref":"#/components/schemas/V1KeyPageChange"},"type":"array","title":"Moves","description":"What changed in the served read."},"strip":{"items":{"$ref":"#/components/schemas/V1KeyPageWeek"},"type":"array","title":"Strip","description":"The last four reads, oldest first."},"history":{"items":{"$ref":"#/components/schemas/V1KeyPageRead"},"type":"array","title":"History","description":"Its reads, newest first, up to 13."}},"type":"object","required":["url","path","title","above_the_fold","moves","strip","history"],"title":"V1KeyPage"},"V1KeyPageChange":{"properties":{"field":{"type":"string","title":"Field","description":"What changed: a field of the above-the-fold read."},"text":{"type":"string","title":"Text"},"previous":{"$ref":"#/components/schemas/JsonValue"},"current":{"$ref":"#/components/schemas/JsonValue"},"direction":{"anyOf":[{"type":"string","enum":["better","worse"]},{"type":"null"}],"title":"Direction","description":"Set only where a measured check flipped."}},"type":"object","required":["field","text","previous","current","direction"],"title":"V1KeyPageChange"},"V1KeyPageDetail":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"url":{"type":"string","title":"Url"},"path":{"type":"string","title":"Path","description":"Pass it, without its leading slash, to read this page alone."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"above_the_fold":{"$ref":"#/components/schemas/V1AboveTheFold"},"moves":{"items":{"$ref":"#/components/schemas/V1KeyPageChange"},"type":"array","title":"Moves","description":"What changed in the served read."},"strip":{"items":{"$ref":"#/components/schemas/V1KeyPageWeek"},"type":"array","title":"Strip","description":"The last four reads, oldest first."},"history":{"items":{"$ref":"#/components/schemas/V1KeyPageRead"},"type":"array","title":"History","description":"Its reads, newest first, up to 13."}},"type":"object","required":["meta","url","path","title","above_the_fold","moves","strip","history"],"title":"V1KeyPageDetail","description":"One key page of the run the Website read serves."},"V1KeyPageRead":{"properties":{"scan_id":{"type":"string","format":"uuid","title":"Scan Id"},"run_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Run Number"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When that weekly read finished."},"captured_at":{"type":"string","format":"date-time","title":"Captured At","description":"When the screenshot was taken: earlier than the week when the read was reused."},"screenshot_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Screenshot Url"},"changes":{"items":{"$ref":"#/components/schemas/V1KeyPageChange"},"type":"array","title":"Changes","description":"What changed since the read before; empty when nothing did."}},"type":"object","required":["scan_id","run_number","completed_at","captured_at","screenshot_url","changes"],"title":"V1KeyPageRead","description":"One weekly read of a key page."},"V1KeyPageWeek":{"properties":{"scan_id":{"type":"string","format":"uuid","title":"Scan Id"},"run_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Run Number"},"changed":{"type":"boolean","title":"Changed"},"direction":{"anyOf":[{"type":"string","enum":["better","worse"]},{"type":"null"}],"title":"Direction","description":"worse where any change made a check fall, else better where one passed."}},"type":"object","required":["scan_id","run_number","changed","direction"],"title":"V1KeyPageWeek"},"V1KeyPages":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"state":{"type":"string","enum":["complete","pending","unavailable"],"title":"State"},"summary":{"anyOf":[{"$ref":"#/components/schemas/V1KeyPagesSummary"},{"type":"null"}]},"key_pages":{"items":{"$ref":"#/components/schemas/V1KeyPage"},"type":"array","title":"Key Pages"}},"type":"object","required":["meta","next_cursor","total","limit","offset","state","summary","key_pages"],"title":"V1KeyPages","examples":[{"key_pages":[],"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"state":"complete","summary":null,"total":0}]},"V1KeyPagesSummary":{"properties":{"since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Since","description":"The previous weekly read the counts compare to."},"changed":{"type":"integer","title":"Changed","description":"Key pages that changed since then."},"say_more":{"type":"integer","title":"Say More","description":"Of them, those whose changes made a check pass."},"say_less":{"type":"integer","title":"Say Less","description":"Of them, those whose changes made a check fall."}},"type":"object","required":["since","changed","say_more","say_less"],"title":"V1KeyPagesSummary"},"V1Keyword":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The keyword's stable id."},"text":{"type":"string","title":"Text"},"status":{"type":"string","enum":["active","paused","archived"],"title":"Status"},"source":{"type":"string","enum":["researched","member"],"title":"Source","description":"Whether this keyword came from research or a member.","default":"researched"},"replaced_by_next_add":{"type":"boolean","title":"Replaced By Next Add","description":"Whether a member's next add in this topic, segment and country would replace this keyword at the cap.","default":false},"topic":{"$ref":"#/components/schemas/KeywordTopic"},"last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Checked At","description":"Latest successful Google check time, or null if none has succeeded."},"searches_mo":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Searches Mo","description":"Monthly Google searches in the topic's market now; null where the vendor had none."},"best_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Rank","description":"Your best position in the latest check's top 10; null when none of your pages is there and before a check read Google."},"top10_naming_you":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top10 Naming You","description":"How many of the latest check's ten results name you, yours included; null before a check read Google."},"clicks_showing_you":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Clicks Showing You","description":"The share of clicks, in points, that land on a page showing you over the period: `figures.mentioned`. Null where the keyword is not measured."},"mentioned_change":{"anyOf":[{"$ref":"#/components/schemas/V1Change"},{"type":"null"}],"description":"The keyword's Mentioned change; null where not measured."},"ai_overview":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ai Overview","description":"Whether the latest check's results page shows an AI Overview; null before a check that loaded it."},"ai_overview_cites_you":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ai Overview Cites You","description":"Whether that AI Overview cites one of your own pages; null when the page has no AI Overview or was not checked for one."},"ai_overview_names_you":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ai Overview Names You","description":"Whether that AI Overview's text names you; null when the page has no AI Overview, was not checked for one, or the reading of its text did not complete."},"ai_overview_names_rivals":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Ai Overview Names Rivals","description":"The rivals you track that AI Overview names, empty when it names none; null when the page has no AI Overview, was not checked for one, or the reading of its text did not complete."},"score":{"anyOf":[{"$ref":"#/components/schemas/ScoreMark"},{"type":"null"}],"description":"Null while Search is not scored."},"trend":{"anyOf":[{"$ref":"#/components/schemas/PromptTrend"},{"type":"null"}],"description":"Null while Search is not scored."},"ai_searches_it":{"items":{"type":"string"},"type":"array","title":"Ai Searches It","description":"The AI engines whose background searches for the topic's prompts contain the keyword."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Keyword's requested country; null means Global."},"language":{"type":"string","title":"Language","description":"Language of this country's keyword.","default":"en"},"master_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Master Text","description":"English source phrase linking country adaptations."},"volume_state":{"type":"string","title":"Volume State","default":"pending","x-extensible-enum":["pending","measured","unavailable","zero","no_data"]},"searches_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Searches Total","description":"Sum of known country volumes; null when all are unknown."},"volume_partial":{"type":"boolean","title":"Volume Partial","description":"True when any country volume is unknown. A confirmed zero contributes zero.","default":false},"countries":{"items":{"$ref":"#/components/schemas/KeywordCountry"},"type":"array","title":"Countries","description":"Country keyword identities, volumes and latest ranks. Global volume targets the United States."}},"type":"object","required":["id","text","status","source","replaced_by_next_add","topic","last_checked_at","searches_mo","best_rank","top10_naming_you","clicks_showing_you","mentioned_change","ai_overview","ai_overview_cites_you","ai_overview_names_you","ai_overview_names_rivals","score","trend","ai_searches_it","country","language","master_text","volume_state","searches_total","volume_partial","countries"],"title":"V1Keyword","description":"A tracked keyword: where a buyer searches Google for a topic."},"V1KeywordConcept":{"properties":{"key":{"type":"string","title":"Key","description":"Stable g:<sha1 of normalised gloss>, or k:<keyword_id> without a gloss."},"text":{"type":"string","title":"Text","description":"Normalised English gloss, or the unglossed keyword's own text."},"topics":{"items":{"$ref":"#/components/schemas/KeywordTopic"},"type":"array","title":"Topics","description":"Distinct member topics in member order."},"topic":{"$ref":"#/components/schemas/KeywordTopic","description":"The first member's topic; use topics.","deprecated":true},"member_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Member Ids","description":"Selected member ids in member order."},"members":{"items":{"$ref":"#/components/schemas/V1Keyword"},"type":"array","title":"Members","description":"Selected members by searches descending, then country; nulls last."},"markets":{"items":{"$ref":"#/components/schemas/KeywordMarket"},"type":"array","title":"Markets","description":"Distinct country and language pairs in member order."},"searches_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Searches Total","description":"Sum of known member volumes; null when all are unknown. Confirmed zero counts as zero."},"volume_partial":{"type":"boolean","title":"Volume Partial","description":"Whether any member volume is unknown."},"best_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Rank","description":"Lowest member rank, never an average."},"best_rank_keyword_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Best Rank Keyword Id","description":"Member holding best_rank; more searches breaks a tie."},"best_rank_country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Best Rank Country","description":"Country holding best_rank; null for Global or no rank."},"members_top10":{"type":"integer","title":"Members Top10","description":"Members ranked 1 to 10, out of the number of members."},"members_checked":{"type":"integer","title":"Members Checked","description":"Members with a fetched check, out of the number of members; 0 means none was checked, so best_rank is null without meaning not in the top 10."},"ai_overview":{"$ref":"#/components/schemas/AIOverviewCounts","description":"Member AI Overview counts on their latest checks."},"mentioned":{"$ref":"#/components/schemas/V1Figure","description":"Search Mentioned over member checks, with change and no trend, shown once any member's check fetched its results."}},"type":"object","required":["key","text","topics","topic","member_ids","members","markets","searches_total","volume_partial","best_rank","best_rank_keyword_id","best_rank_country","members_top10","members_checked","ai_overview","mentioned"],"title":"V1KeywordConcept"},"V1KeywordDetail":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"id":{"type":"string","format":"uuid","title":"Id","description":"The keyword's stable id."},"text":{"type":"string","title":"Text"},"status":{"type":"string","enum":["active","paused","archived"],"title":"Status"},"source":{"type":"string","enum":["researched","member"],"title":"Source","description":"Whether this keyword came from research or a member.","default":"researched"},"replaced_by_next_add":{"type":"boolean","title":"Replaced By Next Add","description":"Whether a member's next add in this topic, segment and country would replace this keyword at the cap.","default":false},"topic":{"$ref":"#/components/schemas/KeywordTopic"},"last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Checked At","description":"Latest successful Google check time, or null if none has succeeded."},"searches_mo":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Searches Mo","description":"Monthly Google searches in the topic's market now; null where the vendor had none."},"best_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Rank","description":"Your best position in the latest check's top 10; null when none of your pages is there and before a check read Google."},"top10_naming_you":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top10 Naming You","description":"How many of the latest check's ten results name you, yours included; null before a check read Google."},"clicks_showing_you":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Clicks Showing You","description":"The share of clicks, in points, that land on a page showing you over the period: `figures.mentioned`. Null where the keyword is not measured."},"mentioned_change":{"anyOf":[{"$ref":"#/components/schemas/V1Change"},{"type":"null"}],"description":"The keyword's Mentioned change; null where not measured."},"ai_overview":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ai Overview","description":"Whether the latest check's results page shows an AI Overview; null before a check that loaded it."},"ai_overview_cites_you":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ai Overview Cites You","description":"Whether that AI Overview cites one of your own pages; null when the page has no AI Overview or was not checked for one."},"ai_overview_names_you":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ai Overview Names You","description":"Whether that AI Overview's text names you; null when the page has no AI Overview, was not checked for one, or the reading of its text did not complete."},"ai_overview_names_rivals":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Ai Overview Names Rivals","description":"The rivals you track that AI Overview names, empty when it names none; null when the page has no AI Overview, was not checked for one, or the reading of its text did not complete."},"score":{"anyOf":[{"$ref":"#/components/schemas/ScoreMark"},{"type":"null"}],"description":"Null while Search is not scored."},"trend":{"anyOf":[{"$ref":"#/components/schemas/PromptTrend"},{"type":"null"}],"description":"Null while Search is not scored."},"ai_searches_it":{"items":{"type":"string"},"type":"array","title":"Ai Searches It","description":"The AI engines whose background searches for the topic's prompts contain the keyword."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Keyword's requested country; null means Global."},"language":{"type":"string","title":"Language","description":"Language of this country's keyword.","default":"en"},"master_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Master Text","description":"English source phrase linking country adaptations."},"volume_state":{"type":"string","title":"Volume State","default":"pending","x-extensible-enum":["pending","measured","unavailable","zero","no_data"]},"searches_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Searches Total","description":"Sum of known country volumes; null when all are unknown."},"volume_partial":{"type":"boolean","title":"Volume Partial","description":"True when any country volume is unknown. A confirmed zero contributes zero.","default":false},"countries":{"items":{"$ref":"#/components/schemas/KeywordCountry"},"type":"array","title":"Countries","description":"Country keyword identities, volumes and latest ranks. Global volume targets the United States."},"rank_delta":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank Delta","description":"Latest weekly rank less the previous report’s rank; negative improves. Null without two comparable ranked reports."},"competitors_delta":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Competitors Delta","description":"Latest weekly competitor results ahead less the previous report’s count. Null without two comparable checked reports."},"period":{"$ref":"#/components/schemas/V1Period"},"figures":{"anyOf":[{"$ref":"#/components/schemas/V1SideFigures"},{"type":"null"}],"description":"The keyword's Search side over the period, with its range and trend: the unread results can only add to it. Null before a report froze a check."},"results":{"items":{"$ref":"#/components/schemas/KeywordResultRow"},"type":"array","title":"Results","description":"The ten results of the latest check Google answered, in order."},"rank_series":{"items":{"$ref":"#/components/schemas/V1RankPoint"},"type":"array","title":"Rank Series","description":"Your best Google position at each weekly report `figures.mentioned.trend` charts, oldest first, with the same `at` and `break` as that trend's point. Empty before a report froze a check."},"prompts":{"items":{"$ref":"#/components/schemas/KeywordPrompt"},"type":"array","title":"Prompts","description":"The topic's prompts, those the engines searched this keyword for first."},"prompts_total":{"type":"integer","title":"Prompts Total","description":"All topic questions before paging; those that searched it come first.","default":0},"results_total":{"type":"integer","title":"Results Total","description":"All ordinary organic Google results before paging; excludes the AI Overview and separate own-page context.","default":0},"markets":{"items":{"$ref":"#/components/schemas/KeywordMarketOption"},"type":"array","title":"Markets","description":"Other tracked markets with the same normalized English keyword meaning in this brand."},"competitors_ahead":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Competitors Ahead","description":"Competitor results above your best rank, or all competitor results in the top ten when you do not rank."},"own_result":{"anyOf":[{"$ref":"#/components/schemas/KeywordResultRow"},{"type":"null"}],"description":"Your highest-ranking organic result, kept separately when it falls outside the result preview; null without one."},"tasks":{"items":{"$ref":"#/components/schemas/V1Action"},"type":"array","title":"Tasks","description":"The live actions about your pages in the results, highest priority first."},"actions_total":{"type":"integer","title":"Actions Total","description":"Every live action about this subject, before the list is cut.","default":0},"next_step_action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Next Step Action Id","description":"The highest-priority live action that awaits a member and whose verb the reader may press; null when there is none."},"next_step":{"anyOf":[{"$ref":"#/components/schemas/V1Action"},{"type":"null"}],"description":"The action `next_step_action_id` names, in the shape of `tasks`."}},"type":"object","required":["meta","id","text","status","source","replaced_by_next_add","topic","last_checked_at","searches_mo","best_rank","top10_naming_you","clicks_showing_you","mentioned_change","ai_overview","ai_overview_cites_you","ai_overview_names_you","ai_overview_names_rivals","score","trend","ai_searches_it","country","language","master_text","volume_state","searches_total","volume_partial","countries","rank_delta","competitors_delta","period","figures","results","rank_series","prompts","prompts_total","results_total","markets","competitors_ahead","own_result","tasks","actions_total","next_step_action_id","next_step"],"title":"V1KeywordDetail"},"V1KeywordMarketRow":{"properties":{"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Requested country; null means Global."},"language":{"type":"string","title":"Language","description":"Keyword language code."},"keywords":{"type":"integer","title":"Keywords","description":"Selected keywords in this market."},"rankings":{"type":"integer","title":"Rankings","description":"Selected keywords in this market with a fetched check in the period."},"searches_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Searches Total","description":"Sum of known volumes; null when all are unknown."},"volume_partial":{"type":"boolean","title":"Volume Partial","description":"Whether any selected keyword volume is unknown."},"top_3":{"type":"integer","title":"Top 3","description":"Keywords whose latest fetched rank is 1 to 3."},"top_10":{"type":"integer","title":"Top 10","description":"Keywords whose latest fetched rank is 1 to 10."},"mentioned":{"$ref":"#/components/schemas/V1Figure","description":"Search Mentioned over this market's selected checks, with change and no trend."}},"type":"object","required":["country","language","keywords","rankings","searches_total","volume_partial","top_3","top_10","mentioned"],"title":"V1KeywordMarketRow"},"V1KeywordTopicRow":{"properties":{"topic":{"$ref":"#/components/schemas/KeywordTopic","description":"The topic these keywords belong to."},"keywords":{"type":"integer","title":"Keywords","description":"Selected keyword and market rows in this topic."},"markets":{"type":"integer","title":"Markets","description":"Distinct selected country and language pairs."},"members":{"items":{"$ref":"#/components/schemas/V1Keyword"},"type":"array","title":"Members","description":"This topic's selected keywords by searches descending, then country; nulls last."},"searches_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Searches Total","description":"Sum of known member volumes; null when all are unknown."},"volume_partial":{"type":"boolean","title":"Volume Partial","description":"Whether any member volume is unknown."},"best_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Rank","description":"Lowest member rank, never an average."},"best_rank_country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Best Rank Country","description":"Country holding best_rank; null for Global or no rank."},"members_checked":{"type":"integer","title":"Members Checked","description":"Members with a fetched check in the brand's history."},"rankings":{"type":"integer","title":"Rankings","description":"Members with a fetched check in the period."},"checked_top_3":{"type":"integer","title":"Checked Top 3","description":"Members checked in the period whose latest rank is 1 to 3, out of rankings."},"checked_top_10":{"type":"integer","title":"Checked Top 10","description":"Members checked in the period whose latest rank is 1 to 10, out of rankings."},"mentioned":{"$ref":"#/components/schemas/V1Figure","description":"The topic's Search Mentioned under the side's coverage rule, with change and no trend."}},"type":"object","required":["topic","keywords","markets","members","searches_total","volume_partial","best_rank","best_rank_country","members_checked","rankings","checked_top_3","checked_top_10","mentioned"],"title":"V1KeywordTopicRow"},"V1Keywords":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headline","description":"One sentence on where the brand ranks on Google's first page, from templates with no model call. It covers the tracked keywords with a measured rank in the requested market, audience and topic, whatever the other filters, grouping and paging. Null in the archived view and while no keyword has a measured rank."},"tracked_total":{"type":"integer","title":"Tracked Total","description":"The tracked view's `total` under this request's filters and grouping.","default":0},"archived_total":{"type":"integer","title":"Archived Total","description":"The archived view's `total` under this request's filters and grouping.","default":0},"period":{"$ref":"#/components/schemas/V1Period"},"keywords":{"items":{"$ref":"#/components/schemas/V1Keyword"},"type":"array","title":"Keywords"},"concepts":{"anyOf":[{"items":{"$ref":"#/components/schemas/V1KeywordConcept"},"type":"array"},{"type":"null"}],"title":"Concepts","description":"Paged concepts when group=concept; omitted otherwise."},"markets":{"anyOf":[{"items":{"$ref":"#/components/schemas/V1KeywordMarketRow"},"type":"array"},{"type":"null"}],"title":"Markets","description":"Paged market rows when group=market; omitted otherwise."},"topics":{"anyOf":[{"items":{"$ref":"#/components/schemas/V1KeywordTopicRow"},"type":"array"},{"type":"null"}],"title":"Topics","description":"Paged topic rows when group=topic; omitted otherwise."},"concepts_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Concepts Total","description":"Concepts in the selection, with grouping or summary."},"keyword_markets_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Keyword Markets Total","description":"Selected keywords, with grouping or summary."},"rankings_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rankings Total","description":"Selected keywords with a fetched check in the period, with grouping or summary."},"summary":{"anyOf":[{"$ref":"#/components/schemas/V1SearchSummary"},{"type":"null"}],"description":"Search summary over the selection when with_summary=true; omitted otherwise."}},"type":"object","required":["meta","next_cursor","total","limit","offset","headline","tracked_total","archived_total","period","keywords"],"title":"V1Keywords","examples":[{"archived_total":0,"headline":null,"keywords":[],"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"period":{"excluded_reports":0,"first_answer_at":null,"last_answer_at":null,"preset":"1w","reports":0},"total":0,"tracked_total":0}]},"V1LatestRead":{"properties":{"actions_found":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Actions Found","description":"Open work frozen when this report counters finished."},"scan_id":{"type":"string","format":"uuid","title":"Scan Id","description":"The scan that produced this weekly report."},"read_at":{"type":"string","format":"date-time","title":"Read At"},"run_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Run Number"}},"type":"object","required":["actions_found","scan_id","read_at","run_number"],"title":"V1LatestRead"},"V1MailAttachment":{"properties":{"name":{"type":"string","title":"Name","description":"The attachment's filename. Open it in your own mailbox."},"size":{"type":"integer","title":"Size","description":"The attachment's size in bytes. Heralded keeps no file bytes."}},"type":"object","required":["name","size"],"title":"V1MailAttachment"},"V1Mailbox":{"properties":{"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address","description":"The connected mailbox account; null once none is connected."},"time_zone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Time Zone","description":"The mailbox's IANA time zone, whose working hours its emails go in."},"connected":{"type":"boolean","title":"Connected","description":"Whether the mailbox can send. Without it nothing goes; a member who can start work may send from their own mail instead."},"sends_as":{"items":{"type":"string"},"type":"array","title":"Sends As","description":"The addresses a task may send from through the mailbox: its own and each alias that passed the From test. The daily sending limit is shared by all addresses of the account."},"default_from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default From","description":"The address the conversation's emails go from (`sender.address`)."},"reconnect_by":{"items":{"type":"string"},"type":"array","title":"Reconnect By","description":"Who can connect the mailbox again, while it is not connected."},"daily_limit":{"type":"integer","title":"Daily Limit","description":"The emails the mailbox sends a day, across every brand sending from it. An approved email past it waits for the next working day (`send.daily_limit`)."},"send":{"anyOf":[{"$ref":"#/components/schemas/V1EmailSend"},{"type":"null"}],"description":"The email on its way, while one is."}},"type":"object","required":["address","time_zone","connected","sends_as","default_from","reconnect_by","daily_limit","send"],"title":"V1Mailbox","description":"The mailbox of this task's sender, with its scheduled send (#9349)."},"V1ManagerPortfolio":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"kind":{"type":"string","const":"managed","title":"Kind","description":"Portfolio of managed organizations.","default":"managed"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"manager_id":{"type":"string","title":"Manager Id"},"manager_name":{"type":"string","title":"Manager Name"},"brands":{"items":{"$ref":"#/components/schemas/ManagerPortfolioBrandRow"},"type":"array","title":"Brands"},"accounts":{"items":{"$ref":"#/components/schemas/ManagerPortfolioAccount"},"type":"array","title":"Accounts"},"brand_total":{"type":"integer","title":"Brand Total","description":"All brands in the managed portfolio before paging."}},"type":"object","required":["meta","next_cursor","total","limit","offset","kind","organization_id","manager_id","manager_name","brands","accounts","brand_total"],"title":"V1ManagerPortfolio","examples":[{"accounts":[],"brand_total":0,"brands":[],"kind":"managed","limit":20,"manager_id":"example","manager_name":"example","meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"organization_id":"00000000-0000-4000-8000-000000000001","total":0}]},"V1MapAlternate":{"properties":{"url":{"type":"string","title":"Url"},"checked":{"type":"boolean","title":"Checked"},"problem":{"anyOf":[{"type":"string","enum":["redirects","broken","no_return"]},{"type":"null"}],"title":"Problem"}},"type":"object","required":["url","checked","problem"],"title":"V1MapAlternate"},"V1MapArchive":{"properties":{"taxonomy":{"type":"string","title":"Taxonomy"},"kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"count":{"type":"integer","title":"Count","default":0},"paged":{"type":"integer","title":"Paged","default":0},"read":{"type":"integer","title":"Read","default":0}},"type":"object","required":["taxonomy","kind","label","count","paged","read"],"title":"V1MapArchive"},"V1MapCategory":{"properties":{"name":{"type":"string","title":"Name"},"group":{"type":"string","title":"Group"},"collection":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection"},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Count"}},"type":"object","required":["name","group","collection","count"],"title":"V1MapCategory"},"V1MapCollection":{"properties":{"key":{"type":"string","title":"Key"},"kind":{"type":"string","title":"Kind","default":"other"},"label":{"type":"string","title":"Label","default":""},"count":{"type":"integer","title":"Count","default":0},"sampled":{"type":"boolean","title":"Sampled","default":false},"read":{"type":"integer","title":"Read","default":0}},"type":"object","required":["key","kind","label","count","sampled","read"],"title":"V1MapCollection"},"V1MapCounts":{"properties":{"broken":{"type":"integer","title":"Broken","default":0},"orphans":{"type":"integer","title":"Orphans","default":0},"agent_unreachable":{"type":"integer","title":"Agent Unreachable","default":0}},"type":"object","required":["broken","orphans","agent_unreachable"],"title":"V1MapCounts"},"V1MapFinding":{"properties":{"id":{"type":"string","title":"Id"},"area":{"type":"string","enum":["positioning","content","proof","conversion","design","seo","ai_visibility","technical"],"title":"Area"},"detail":{"type":"string","title":"Detail"},"severity":{"type":"string","enum":["issue","improve","info"],"title":"Severity"},"pages":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages","description":"Every page the finding names across the run; null when the stored graph has no count."}},"type":"object","required":["id","area","detail","severity","pages"],"title":"V1MapFinding"},"V1MapFolder":{"properties":{"path":{"type":"string","title":"Path","description":"Pass as folder to open it."},"pages":{"type":"integer","title":"Pages","description":"Every page under it."},"issue":{"type":"integer","title":"Issue"},"improve":{"type":"integer","title":"Improve"},"broken":{"type":"integer","title":"Broken"}},"type":"object","required":["path","pages","issue","improve","broken"],"title":"V1MapFolder"},"V1MapImages":{"properties":{"count":{"type":"integer","title":"Count"},"missing_alt":{"type":"integer","title":"Missing Alt"}},"type":"object","required":["count","missing_alt"],"title":"V1MapImages"},"V1MapLink":{"properties":{"source":{"type":"string","title":"Source"},"target":{"type":"string","title":"Target"},"kind":{"type":"string","title":"Kind","default":"link"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"rendered":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Rendered","description":"Present only after JavaScript runs; Full and weekly reads."}},"type":"object","required":["source","target","kind","region","label","rendered"],"title":"V1MapLink"},"V1MapPage":{"properties":{"url":{"type":"string","title":"Url"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"host":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Host","description":"The host of a page outside the site's own, for grouping; null on the site's."},"found_on":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Found On"},"category":{"anyOf":[{"$ref":"#/components/schemas/V1MapCategory"},{"type":"null"}]},"alternates":{"items":{"$ref":"#/components/schemas/V1MapAlternate"},"type":"array","title":"Alternates"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status"},"unread":{"type":"boolean","title":"Unread","description":"Listed but never read, with no status or facts; collapse these by collection.","default":false},"depth":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Depth","description":"Clicks from the homepage."},"orphan":{"type":"boolean","title":"Orphan"},"screenshot_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Screenshot Url"},"collection":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection"},"archive":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Archive"},"findings":{"items":{"type":"string"},"type":"array","title":"Findings"},"notes":{"additionalProperties":{"type":"string"},"type":"object","title":"Notes","description":"This page's notes by finding id, frozen with the run; empty when the stored graph has none."},"severity":{"anyOf":[{"type":"string","enum":["dead","issue","improve"]},{"type":"null"}],"title":"Severity"},"above_the_fold":{"anyOf":[{"$ref":"#/components/schemas/V1AboveTheFold"},{"type":"null"}]},"facts":{"anyOf":[{"$ref":"#/components/schemas/V1MapPageFacts"},{"type":"null"}]}},"type":"object","required":["url","language","host","found_on","category","alternates","title","type","status","unread","depth","orphan","screenshot_url","collection","archive","findings","notes","severity","above_the_fold","facts"],"title":"V1MapPage"},"V1MapPageFacts":{"properties":{"words":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Words"},"text":{"anyOf":[{"$ref":"#/components/schemas/V1MapText"},{"type":"null"}],"description":"Characters without and with JavaScript; Full and weekly reads."},"noindex":{"type":"boolean","title":"Noindex","default":false},"canonical_elsewhere":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Elsewhere"},"meta_description":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Meta Description"},"h1":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"H1"},"images":{"anyOf":[{"$ref":"#/components/schemas/V1MapImages"},{"type":"null"}]},"form_fields":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Form Fields"},"lastmod":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lastmod"}},"type":"object","required":["words","text","noindex","canonical_elsewhere","meta_description","h1","images","form_fields","lastmod"],"title":"V1MapPageFacts"},"V1MapText":{"properties":{"server":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Server"},"rendered":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rendered"}},"type":"object","required":["server","rendered"],"title":"V1MapText"},"V1MovingAwayFrom":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"period":{"$ref":"#/components/schemas/V1Period","description":"The period and reports the shares were read over."},"filters":{"$ref":"#/components/schemas/FigureFilters","description":"The filters the answers and pages were read under."},"labels":{"items":{"$ref":"#/components/schemas/MovingAwayLabel"},"type":"array","title":"Labels","description":"The labels the brand is moving away from, in the order its profile lists them. Empty when it names none."}},"type":"object","required":["meta","period","filters","labels"],"title":"V1MovingAwayFrom"},"V1Offer":{"properties":{"version":{"type":"integer","title":"Version","description":"1 for the first terms on the task, one higher per change."},"state":{"type":"string","enum":["open","agreed","countered","asked_free","declined","superseded"],"title":"State","description":"`open` until a member answers it; `superseded` once a newer version replaced it unanswered."},"options":{"items":{"$ref":"#/components/schemas/V1OfferOption"},"type":"array","title":"Options","description":"Each priced option."},"labelling":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Labelling","description":"What they said about labelling the placement."},"conditions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conditions","description":"Any other condition they set."},"payment_due":{"anyOf":[{"type":"string","x-extensible-enum":["upfront","after_publication"]},{"type":"null"}],"title":"Payment Due","description":"When they are paid for the offer: `upfront`, or `after_publication` once it is live; null where they did not say."},"made_by":{"type":"string","enum":["reading","member"],"title":"Made By","description":"`reading` for terms read from their email, `member` for terms a member corrected or added."},"email_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Email Id","description":"The email the terms came in; null for a member's version."},"decision":{"anyOf":[{"$ref":"#/components/schemas/V1OfferDecision"},{"type":"null"}],"description":"The member's answer to this version."},"decided_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Decided At","description":"When it was answered."},"told_email_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Told Email Id","description":"The email of ours that told them the decision; null while it is not told, or was never decided."},"told_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Told At","description":"When that email went: the time the decision reached them."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the version was made."},"ways":{"items":{"type":"string","enum":["agree","offer_less","ask_free","decline"]},"type":"array","title":"Ways","description":"The ways to answer it while it is open: agree to an option, offer less, ask for the free option, or decline."},"needs_article":{"type":"boolean","title":"Needs Article","description":"Whether agreeing needs an article from the brand, which they asked for: agreeing then says who writes it, Heralded for `article_credits` content credits or the brand itself for none.","default":false},"article_credits":{"type":"integer","title":"Article Credits","description":"The content credits Heralded writing the article costs; 0 when agreeing needs no article.","default":0}},"type":"object","required":["version","state","options","labelling","conditions","payment_due","made_by","email_id","decision","decided_at","told_email_id","told_at","created_at","ways","needs_article","article_credits"],"title":"V1Offer","description":"One version of the terms on the table of a task with a source\n(#9345). Private to the brand."},"V1OfferDecision":{"properties":{"way":{"type":"string","enum":["agree","offer_less","ask_free","decline"],"title":"Way","description":"How the member answered the offer."},"option":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Option","description":"The agreed or countered option's zero-based index."},"option_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Option Key","description":"The agreed or countered option's key."},"writer":{"anyOf":[{"type":"string","enum":["them","heralded","member","none"]},{"type":"null"}],"title":"Writer","description":"Who writes the article the agreement needs: `them`, `heralded`, `member` (the brand's own team) or `none` where no article is needed. Set when the member agrees to an option that carries one; null on every other decision."},"amount":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Amount","description":"What the brand offered instead."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"The currency of that amount."}},"type":"object","required":["way","option","option_key","writer","amount","currency"],"title":"V1OfferDecision"},"V1OfferOption":{"properties":{"amount":{"type":"string","title":"Amount","description":"The price, as a decimal string."},"currency":{"type":"string","title":"Currency","description":"The ISO 4217 currency code."},"includes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Includes","description":"What this option gets the brand."},"duration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Duration","description":"How long it stays live."},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"Stable option identity; null on legacy terms."},"deliverable":{"anyOf":[{"$ref":"#/components/schemas/OfferDeliverable"},{"type":"null"}],"description":"What this option delivers."},"labelling":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Labelling","description":"How the placement is labelled."},"conditions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conditions","description":"Conditions specific to this option."},"writer":{"anyOf":[{"type":"string","enum":["brand","them","none"]},{"type":"null"}],"title":"Writer","description":"Who supplies the piece; null when uncertain, none when no piece is needed."},"requirements":{"anyOf":[{"$ref":"#/components/schemas/OfferRequirements"},{"type":"null"}],"description":"Requirements specific to this option."},"payment_due":{"anyOf":[{"type":"string","x-extensible-enum":["upfront","after_publication"]},{"type":"null"}],"title":"Payment Due","description":"When this option is paid, only where it differs from the offer's `payment_due`; `terms.payment_due` is the one that applies."},"terms":{"$ref":"#/components/schemas/OptionTerms","description":"Effective labelling, conditions and requirements, including whole-offer terms. The option's other term fields retain their stored scope for editing."},"change":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Change","description":"What changed in the terms to decide on."},"needs_article":{"type":"boolean","title":"Needs Article","description":"Whether agreeing to this option needs an article choice.","default":false},"article_credits":{"type":"integer","title":"Article Credits","description":"Content credits if Heralded writes this option's article.","default":0}},"type":"object","required":["amount","currency","includes","duration","key","deliverable","labelling","conditions","writer","requirements","payment_due","terms","change","needs_article","article_credits"],"title":"V1OfferOption"},"V1Overview":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"period":{"$ref":"#/components/schemas/V1Period"},"sides_available":{"items":{"type":"string","enum":["ai","search"]},"type":"array","title":"Sides Available","description":"The sides the period's reports observed: `ai`, and `search` once a report checked keywords. A read of reports without search observations states `[\"ai\"]`, and `all` is then the AI side."},"heralded_score":{"$ref":"#/components/schemas/V1Figure"},"mentioned":{"$ref":"#/components/schemas/V1Figure"},"recommended":{"$ref":"#/components/schemas/V1Figure"},"understood":{"$ref":"#/components/schemas/V1Figure"},"praised":{"$ref":"#/components/schemas/V1Figure"},"counts":{"$ref":"#/components/schemas/WorkCounts","description":"Current work populations, excluding setup; your_turn follows the viewer scope."},"sides":{"$ref":"#/components/schemas/V1Sides","description":"The Heralded Score, Mentioned and Recommended on each side, whichever `side` the top-level figures read. A side not measured has a null value."},"attribution":{"anyOf":[{"$ref":"#/components/schemas/Attribution"},{"type":"null"}]},"source_citation_evidence":{"type":"string","enum":["complete","partial","unavailable"],"title":"Source Citation Evidence","default":"complete"},"source_unavailable_scans":{"type":"integer","title":"Source Unavailable Scans","default":0},"report":{"anyOf":[{"$ref":"#/components/schemas/V1LatestRead"},{"type":"null"}],"description":"The latest weekly report and its frozen count."},"latest_read":{"anyOf":[{"$ref":"#/components/schemas/V1LatestRead"},{"type":"null"}]},"headline":{"anyOf":[{"$ref":"#/components/schemas/V1Headline"},{"type":"null"}]},"answers_citing_you":{"anyOf":[{"$ref":"#/components/schemas/V1Count"},{"type":"null"}]},"sources_mentioning_you":{"anyOf":[{"$ref":"#/components/schemas/V1Count"},{"type":"null"}],"description":"Third-party sites with a read page naming you, out of third-party sites read, over `period`: the Sources page's sites naming you. Null before the first report and while citation evidence is unavailable."},"rivals":{"items":{"$ref":"#/components/schemas/V1Competitor"},"type":"array","title":"Rivals"},"competitor_rank":{"anyOf":[{"$ref":"#/components/schemas/V1CompetitorRank"},{"type":"null"}],"description":"Your rank by Heralded Score among the tracked competitors over the period, on the side read; null while your score or every competitor's is unmeasured, and under `lean`."},"sources":{"items":{"$ref":"#/components/schemas/V1CitedSource"},"type":"array","title":"Sources"},"actions":{"items":{"$ref":"#/components/schemas/V1Action"},"type":"array","title":"Actions"},"next_weekly_scan_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Weekly Scan At"},"next_daily_scan_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Daily Scan At"},"daily_scans_since_weekly":{"type":"integer","title":"Daily Scans Since Weekly"},"open_action_count":{"type":"integer","title":"Open Action Count","description":"Alias of counts.open.","deprecated":true},"readiness":{"anyOf":[{"$ref":"#/components/schemas/V1Readiness"},{"type":"null"}]},"heralded_score_band":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Heralded Score Band","description":"The band of `score_bands` the Heralded Score falls in; null without a score."},"score_bands":{"items":{"$ref":"#/components/schemas/ScoreBand"},"type":"array","title":"Score Bands","description":"Every Heralded Score band, lowest first."},"score_context":{"anyOf":[{"$ref":"#/components/schemas/V1ScoreContext"},{"type":"null"}],"description":"What the latest weekly scan's score was read from; null before one."},"since_started":{"anyOf":[{"$ref":"#/components/schemas/V1SinceStarted"},{"type":"null"}],"description":"The Heralded Score's move since the first weekly scan, off the period's figures; null before the first."},"verified_actions":{"$ref":"#/components/schemas/V1VerifiedActions"},"diagnosis":{"anyOf":[{"$ref":"#/components/schemas/V1Diagnosis"},{"type":"null"}],"description":"What rivals win over the last week and the drafts ready to answer it; null unless `with_diagnosis`."}},"type":"object","required":["meta","period","sides_available","heralded_score","mentioned","recommended","understood","praised","counts","sides","attribution","source_citation_evidence","source_unavailable_scans","report","latest_read","headline","answers_citing_you","sources_mentioning_you","rivals","competitor_rank","sources","actions","next_weekly_scan_at","next_daily_scan_at","daily_scans_since_weekly","open_action_count","readiness","heralded_score_band","score_bands","score_context","since_started","verified_actions","diagnosis"],"title":"V1Overview"},"V1OwnedPage":{"properties":{"funnel":{"$ref":"#/components/schemas/PageFunnel"},"id":{"type":"string","format":"uuid","title":"Id"},"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"page_type":{"type":"string","title":"Page Type"},"citations":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Citations","description":"Citations in the period's counted answers. Null where a weekly scan it covers could not keep all its citations."},"prompts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompts","description":"Tracked prompts an answer cited the page on. Null where a weekly scan it covers could not keep all its citations."},"ai_visits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ai Visits","description":"Sessions GA4 attributes to AI assistants over coverage, a floor. Null without a complete read covering this page."},"crawler_hits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Crawler Hits","description":"Served requests from all listed bots, frozen in the newest pinned weekly scan over crawler_hits_days: 28 whole days ending two days before it started. Plugin counts are a floor. Null without a recorded measurement covering the page."},"crawler_bots":{"items":{"$ref":"#/components/schemas/V1CrawlerBot"},"type":"array","title":"Crawler Bots","description":"The crawlers behind crawler_hits."},"rubric":{"anyOf":[{"$ref":"#/components/schemas/V1PageRubric"},{"type":"null"}],"description":"Null on a page the rubric does not audit, such as a legal page."}},"type":"object","required":["funnel","id","url","title","page_type","citations","prompts","ai_visits","crawler_hits","crawler_bots","rubric"],"title":"V1OwnedPage"},"V1Page":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"engines":{"items":{"$ref":"#/components/schemas/V1PageCitingEngine"},"type":"array","title":"Engines","description":"The page's citations and citing-answer share per engine under the period and filters."},"paused_engines":{"items":{"type":"string"},"type":"array","title":"Paused Engines","description":"Engines paused in the selected report, under the engine filter."},"funnel":{"$ref":"#/components/schemas/PageFunnel"},"funnel_series":{"items":{"$ref":"#/components/schemas/PageFunnelPoint"},"type":"array","title":"Funnel Series","description":"The funnel on each weekly scan's 28-day window, oldest first, back as far as the plan's history reads. Empty without a weekly scan in that history."},"search":{"anyOf":[{"$ref":"#/components/schemas/V1PageSearch"},{"type":"null"}]},"takes":{"anyOf":[{"$ref":"#/components/schemas/PageTakeList"},{"type":"null"}],"description":"What AI took from the page, read from the evidence frozen with each scan and pinned by as_of. Present with with_takes. Open an item's answer at answers/{answer_read_id}."},"answers_link":{"anyOf":[{"$ref":"#/components/schemas/AnswersLink"},{"type":"null"}]},"piece":{"anyOf":[{"$ref":"#/components/schemas/TopicPiece"},{"type":"null"}]},"page_type_decided_by":{"type":"string","enum":["model","model_url","rule"],"title":"Page Type Decided By"},"period":{"$ref":"#/components/schemas/V1Period"},"id":{"type":"string","format":"uuid","title":"Id"},"url":{"type":"string","title":"Url"},"path":{"type":"string","title":"Path"},"section":{"type":"string","title":"Section"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"page_type":{"type":"string","title":"Page Type"},"page_type_source":{"type":"string","enum":["member","heralded"],"title":"Page Type Source"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topic","description":"The tracked prompt the content pass matched it to."},"topics":{"items":{"type":"string"},"type":"array","title":"Topics","description":"Tracked topics whose topic read lists this page."},"topic_source":{"type":"string","enum":["member","heralded"],"title":"Topic Source"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why the latest content pass wants the page improved."},"cited_in":{"type":"string","enum":["tracked","elsewhere","search_only","never"],"title":"Cited In"},"change":{"$ref":"#/components/schemas/V1PageChange"},"citations":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Citations","description":"Null where a weekly scan it covers could not keep all its citations."},"citation_share_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Citation Share Pct","description":"This page's share of the citations the brand's own pages earn. Null where a weekly scan it covers could not keep all its citations."},"prompts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompts","description":"Null where a weekly scan it covers could not keep all its citations."},"prompts_tracked":{"type":"integer","title":"Prompts Tracked"},"engines_citing":{"type":"integer","title":"Engines Citing","description":"The engines citing the page. A floor unless citation_evidence is complete."},"engines_read":{"type":"integer","title":"Engines Read"},"first_cited_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Cited At","description":"The first kept citation's time. A floor unless citation_evidence is complete."},"last_cited_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Cited At","description":"The last kept citation's time. A floor unless citation_evidence is complete."},"citation_evidence":{"type":"string","enum":["complete","partial","unavailable"],"title":"Citation Evidence","default":"complete"},"unavailable_scans":{"type":"integer","title":"Unavailable Scans","default":0},"crawled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Crawled At"},"changed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Changed At","description":"When the crawl last saw its content change."},"read":{"type":"boolean","title":"Read","description":"Whether Heralded holds the page's text."},"unread_state":{"anyOf":[{"type":"string","enum":["blocked","failed","not_tried"]},{"type":"null"}],"title":"Unread State"},"delivered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Delivered At","description":"When Heralded delivered the page, if it did."},"delivery_cited_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Delivery Cited At","description":"The first weekly scan after the delivery that cited the page."},"search_clicks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Clicks","description":"Search Console clicks over the bound property's 28-day read; null without a read returning the page."},"trend":{"items":{"$ref":"#/components/schemas/V1PageTrendPoint"},"type":"array","title":"Trend","description":"Citations in each weekly scan."},"cited_on":{"items":{"$ref":"#/components/schemas/V1PagePrompt"},"type":"array","title":"Cited On"},"rubric":{"anyOf":[{"$ref":"#/components/schemas/V1PageRubricDetail"},{"type":"null"}]},"checks":{"items":{"$ref":"#/components/schemas/V1PageCheck"},"type":"array","title":"Checks","description":"Each check the latest content pass made of the page against rival pages."},"rival_urls":{"items":{"type":"string"},"type":"array","title":"Rival Urls","description":"The rival pages those checks compared it with."},"crawler_hits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Crawler Hits"},"crawler_hits_days":{"type":"integer","title":"Crawler Hits Days"},"crawler_bots":{"items":{"$ref":"#/components/schemas/V1CrawlerBot"},"type":"array","title":"Crawler Bots"},"ai_visits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ai Visits"},"ai_visits_by_assistant":{"items":{"$ref":"#/components/schemas/V1AssistantVisits"},"type":"array","title":"Ai Visits By Assistant"},"coverage":{"anyOf":[{"$ref":"#/components/schemas/V1VisitCoverage"},{"type":"null"}]},"findings":{"items":{"$ref":"#/components/schemas/V1PageFinding"},"type":"array","title":"Findings","description":"The Website findings naming the page, most points off the score first, from the run the brand's Website read serves."},"above_the_fold":{"anyOf":[{"$ref":"#/components/schemas/V1AboveTheFold"},{"type":"null"}],"description":"What the page shows before scrolling; null unless it is a key page."},"against_brand":{"anyOf":[{"$ref":"#/components/schemas/V1AgainstBrand"},{"type":"null"}],"description":"The page against that run's brief: the claims it states and those its text contradicts; null without a brief."},"copy_and_proof":{"anyOf":[{"$ref":"#/components/schemas/V1CopyAndProof"},{"type":"null"}],"description":"Its copy and proof as that run read them; null where it read no text."},"facts":{"anyOf":[{"$ref":"#/components/schemas/V1PageFacts"},{"type":"null"}],"description":"What that run's crawl read on the page: words, images, clicks from the homepage, links in and its own last-modified date; null where the run's site graph does not hold the page."},"takes_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Takes Total","description":"All assessments of this page before paging.","readOnly":true}},"type":"object","required":["meta","engines","paused_engines","funnel","funnel_series","search","takes","answers_link","piece","page_type_decided_by","period","id","url","path","section","title","page_type","page_type_source","topic","topics","topic_source","reason","cited_in","change","citations","citation_share_pct","prompts","prompts_tracked","engines_citing","engines_read","first_cited_at","last_cited_at","citation_evidence","unavailable_scans","crawled_at","changed_at","read","unread_state","delivered_at","delivery_cited_at","search_clicks","trend","cited_on","rubric","checks","rival_urls","crawler_hits","crawler_hits_days","crawler_bots","ai_visits","ai_visits_by_assistant","coverage","findings","above_the_fold","against_brand","copy_and_proof","facts","takes_total"],"title":"V1Page"},"V1PageAiVisits":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"url":{"type":"string","title":"Url"},"ai_visits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ai Visits","description":"Sessions GA4 attributes to AI assistants, a floor because visits often carry no referrer. Null without a complete read covering this page."}},"type":"object","required":["id","url","ai_visits"],"title":"V1PageAiVisits"},"V1PageAnswers":{"properties":{"url":{"type":"string","title":"Url"}},"type":"object","required":["url"],"title":"V1PageAnswers"},"V1PageChange":{"properties":{"kind":{"type":"string","enum":["improved","dropped","new","quiet","last_cited","never","unmeasured"],"title":"Kind"},"delta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta","description":"Average citations per weekly scan gained or lost against the period's baseline; null where the kind is not a quantity."},"at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"At","description":"On last_cited, when AI last cited the page."}},"type":"object","required":["kind","delta","at"],"title":"V1PageChange"},"V1PageCheck":{"properties":{"key":{"type":"string","title":"Key"},"short":{"type":"boolean","title":"Short","description":"Whether the page fell short on the check."},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"},"insight":{"anyOf":[{"$ref":"#/components/schemas/ServedInsight"},{"type":"null"}],"description":"On a check the page fell short on: the rewrite that fits it and the page's rewrite already filed."}},"type":"object","required":["key","short","detail","insight"],"title":"V1PageCheck"},"V1PageCitationReport":{"properties":{"measured_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Measured Domain"},"key":{"anyOf":[{"$ref":"#/components/schemas/ComparabilityKey"},{"type":"null"}]},"breaks":{"items":{"$ref":"#/components/schemas/KeyChange"},"type":"array","title":"Breaks"},"prompts_changed":{"type":"boolean","title":"Prompts Changed","default":false},"run_number":{"type":"integer","title":"Run Number"},"completed_at":{"type":"string","format":"date-time","title":"Completed At"},"citations":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Citations"},"degraded":{"type":"boolean","title":"Degraded"},"break":{"anyOf":[{"$ref":"#/components/schemas/TrendBreak"},{"type":"null"}],"readOnly":true}},"type":"object","required":["measured_domain","key","breaks","prompts_changed","run_number","completed_at","citations","degraded","break"],"title":"V1PageCitationReport"},"V1PageCitingEngine":{"properties":{"engine":{"type":"string","enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"title":"Engine"},"citations":{"type":"integer","title":"Citations"},"answers":{"type":"integer","title":"Answers"},"answers_share_pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Answers Share Pct"}},"type":"object","required":["engine","citations","answers","answers_share_pct"],"title":"V1PageCitingEngine"},"V1PageCitingPrompt":{"properties":{"prompt_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Prompt Id"},"text":{"type":"string","title":"Text"},"citations":{"type":"integer","title":"Citations"},"answers":{"type":"integer","title":"Answers"}},"type":"object","required":["prompt_id","text","citations","answers"],"title":"V1PageCitingPrompt"},"V1PageClaim":{"properties":{"axis":{"type":"string","enum":["category","target_buyer","differentiation"],"title":"Axis"},"claim":{"type":"string","title":"Claim"},"stated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Stated","description":"Whether the page states it; null where the read was unclear or not asked."}},"type":"object","required":["axis","claim","stated"],"title":"V1PageClaim"},"V1PageConflict":{"properties":{"axis":{"type":"string","title":"Axis"},"claim":{"type":"string","title":"Claim"},"passage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Passage"}},"type":"object","required":["axis","claim","passage"],"title":"V1PageConflict"},"V1PageFacts":{"properties":{"words":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Words","description":"Words in the page's readable text."},"images":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Images","description":"Images on the page."},"images_missing_alt":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Images Missing Alt","description":"Images with no alt text."},"clicks_from_home":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Clicks From Home","description":"Clicks along the shortest path of links from the homepage; null when no path reaches the page."},"links_in":{"type":"integer","title":"Links In","description":"Links from the site's other read pages to this one."},"last_modified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Modified","description":"The page's own last-modified date."},"load_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Load Ms","description":"Milliseconds until the page's main content shows on a simulated mobile load (PageSpeed's Largest Contentful Paint), measured on key pages in weekly reports; null on other pages or where PageSpeed did not measure it."}},"type":"object","required":["words","images","images_missing_alt","clicks_from_home","links_in","last_modified","load_ms"],"title":"V1PageFacts","description":"What the run's crawl read on the page, from its frozen site graph."},"V1PageFinding":{"properties":{"id":{"type":"string","title":"Id","description":"The finding's stable identifier."},"area":{"type":"string","enum":["positioning","content","proof","conversion","design","seo","ai_visibility","technical"],"title":"Area","description":"The Website area the finding belongs to."},"group":{"type":"string","enum":["message","experience","reach"],"title":"Group","description":"The Website group the area belongs to."},"state":{"type":"string","enum":["measured","unmeasured","not_applicable"],"title":"State","description":"measured, unmeasured (with a reason) or not_applicable. Only a measured finding enters a score, and not measured is never zero."},"reason":{"anyOf":[{"type":"string","x-extensible-enum":["no_brief","not_in_quick","not_read","pending","provider_unavailable","truncated"]},{"type":"null"}],"title":"Reason","description":"Why it was not measured; null when measured. not_in_quick is a check a Quick audit leaves to Base. New values may be added."},"severity":{"type":"string","enum":["issue","improve","info"],"title":"Severity","description":"issue, improve, or info: measured and shown, outside every score."},"share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Share","description":"How much of what it reads holds the finding, 0 to 1; null unless measured."},"passed":{"type":"boolean","title":"Passed","description":"Whether the measured check passed; false when it failed or was not measured."},"detail":{"type":"string","title":"Detail","description":"What was found; on an unmeasured finding, why it could not be measured."},"pages":{"anyOf":[{"$ref":"#/components/schemas/V1WebsiteFindingPages"},{"type":"null"}],"description":"The pages it names; null for a finding about the whole site."},"sampled":{"type":"boolean","title":"Sampled","description":"Counted from a sample of a collection or archive."},"points_off_area":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Points Off Area","description":"What it takes off its area's score."},"fix_steps":{"items":{"type":"string"},"type":"array","title":"Fix Steps","description":"Steps that address this finding."},"action":{"anyOf":[{"$ref":"#/components/schemas/V1WebsiteAction"},{"type":"null"}],"description":"The newest open work filed for it; null where none is, always on info."},"held_back":{"type":"boolean","title":"Held Back","description":"A suggestion covering it waits beyond the plan's open suggestions, so Actions does not show it yet; `action` is null then.","default":false},"can_add":{"type":"boolean","title":"Can Add","description":"A member can add it to Actions as their own request: the brand's latest weekly read holds it, no shown action covers it, and either a held-back suggestion covers it or nothing started or settled does. Always false on info.","default":false},"insight":{"anyOf":[{"$ref":"#/components/schemas/ServedInsight"},{"type":"null"}],"description":"The work that fits it and the work filed from it; null on info, and on a page whose finding is another page's work."},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"This page's own finding note, when the read kept one."},"others":{"type":"integer","title":"Others","description":"Other pages named by the finding."},"finding_pages_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Finding Pages Total","description":"All pages named by this finding before paging.","readOnly":true}},"type":"object","required":["id","area","group","state","reason","severity","share","passed","detail","pages","sampled","points_off_area","fix_steps","action","held_back","can_add","insight","note","others","finding_pages_total"],"title":"V1PageFinding"},"V1PagePillar":{"properties":{"key":{"type":"string","enum":["eligible","answers","substance"],"title":"Key"},"status":{"type":"string","enum":["pass","fail","unmeasured"],"title":"Status"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"What a failing pillar measured; null otherwise."}},"type":"object","required":["key","status","detail"],"title":"V1PagePillar"},"V1PagePrompt":{"properties":{"prompt_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Prompt Id"},"text":{"type":"string","title":"Text"},"intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent"},"query_id":{"type":"string","title":"Query Id"},"answers":{"items":{"$ref":"#/components/schemas/V1PageRead"},"type":"array","title":"Answers"}},"type":"object","required":["prompt_id","text","intent","query_id","answers"],"title":"V1PagePrompt"},"V1PageRead":{"properties":{"engine":{"type":"string","enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"title":"Engine"},"cites_page":{"type":"boolean","title":"Cites Page","description":"Whether this answer cited the page."},"mentioned":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Mentioned"},"recommended":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Recommended"},"answered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Answered At"},"answer_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Answer Id"},"strength":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Strength"},"states":{"anyOf":[{"$ref":"#/components/schemas/AnswerReadStates"},{"type":"null"}]}},"type":"object","required":["engine","cites_page","mentioned","recommended","answered_at","answer_id","strength","states"],"title":"V1PageRead"},"V1PageRevenue":{"properties":{"revenue":{"type":"number","title":"Revenue","description":"Revenue in the read's currency, a minimum."},"orders":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Orders","description":"Purchases; null for a product, counted in units."},"key_events":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Key Events","description":"Key events; null for a product."},"visits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Visits","description":"Google Analytics sessions; null where it gives none for the cut."},"items":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Items","description":"Units bought; only for a product."},"average_order":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Order","description":"Revenue per order; null without orders."},"conversion":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Conversion","description":"Orders per visit in [0, 1]; null without a visit count."},"path":{"type":"string","title":"Path","description":"The landing page's path on your site."},"page_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Page Id","description":"Your page's id, as the pages reads name it; null where none matched."},"assistants":{"items":{"$ref":"#/components/schemas/V1AssistantRevenue"},"type":"array","title":"Assistants","description":"By assistant, most revenue first."},"topics":{"items":{"$ref":"#/components/schemas/V1RevenueTopic"},"type":"array","title":"Topics","description":"The topics whose answers in the period cite the page, most answers first."},"questions":{"items":{"$ref":"#/components/schemas/V1RevenueQuestion"},"type":"array","title":"Questions","description":"The 5 questions whose answers cite the page most."},"questions_total":{"type":"integer","title":"Questions Total","description":"Every question whose answers cite the page."}},"type":"object","required":["revenue","orders","key_events","visits","items","average_order","conversion","path","page_id","assistants","topics","questions","questions_total"],"title":"V1PageRevenue"},"V1PageRubric":{"properties":{"priority":{"type":"string","enum":["ineligible","unmeasured","answer_gap","substance_gap","ready"],"title":"Priority","description":"The rubric's finding: ineligible, answer_gap and substance_gap are gaps."},"score":{"type":"number","title":"Score","description":"Value times gap as the newest scan with page records scored the page; zero without a gap. Higher is a better fix."}},"type":"object","required":["priority","score"],"title":"V1PageRubric"},"V1PageRubricDetail":{"properties":{"priority":{"type":"string","enum":["ineligible","unmeasured","answer_gap","substance_gap","ready"],"title":"Priority","description":"The rubric's finding: ineligible, answer_gap and substance_gap are gaps."},"score":{"type":"number","title":"Score","description":"Value times gap as the newest scan with page records scored the page; zero without a gap. Higher is a better fix."},"pillars":{"items":{"$ref":"#/components/schemas/V1PagePillar"},"type":"array","title":"Pillars"}},"type":"object","required":["priority","score","pillars"],"title":"V1PageRubricDetail"},"V1PageSearch":{"properties":{"state":{"type":"string","enum":["ready","not_connected","unavailable","no_data"],"title":"State"},"unavailable_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unavailable Reason"},"window_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Window Start"},"window_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Window End"},"clicks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Clicks"},"impressions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Impressions"},"position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Position"},"top_queries":{"items":{"type":"string"},"type":"array","title":"Top Queries","default":[]},"top_queries_read":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Top Queries Read"},"pages_read":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages Read"}},"type":"object","required":["state","unavailable_reason","window_start","window_end","clicks","impressions","position","top_queries","top_queries_read","pages_read"],"title":"V1PageSearch"},"V1PageTrendPoint":{"properties":{"key":{"anyOf":[{"$ref":"#/components/schemas/ComparabilityKey"},{"type":"null"}]},"breaks":{"items":{"$ref":"#/components/schemas/KeyChange"},"type":"array","title":"Breaks"},"prompts_changed":{"type":"boolean","title":"Prompts Changed","default":false},"run_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Run Number"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"},"citations":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Citations","description":"Null where the weekly scan could not keep all its citations."},"break":{"anyOf":[{"$ref":"#/components/schemas/TrendBreak"},{"type":"null"}],"readOnly":true}},"type":"object","required":["key","breaks","prompts_changed","run_number","completed_at","citations","break"],"title":"V1PageTrendPoint"},"V1Pages":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"resolved_page_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Resolved Page Id"},"period":{"$ref":"#/components/schemas/V1Period"},"coverage":{"anyOf":[{"$ref":"#/components/schemas/V1VisitCoverage"},{"type":"null"}]},"crawler_hits_days":{"type":"integer","title":"Crawler Hits Days"},"pages":{"items":{"$ref":"#/components/schemas/V1OwnedPage"},"type":"array","title":"Pages"}},"type":"object","required":["meta","next_cursor","total","limit","offset","resolved_page_id","period","coverage","crawler_hits_days","pages"],"title":"V1Pages","examples":[{"coverage":null,"crawler_hits_days":0,"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"pages":[],"period":{"excluded_reports":0,"first_answer_at":null,"last_answer_at":null,"preset":"1w","reports":0},"resolved_page_id":null,"total":0}]},"V1PagesWithFindings":{"properties":{"count":{"type":"integer","title":"Count","description":"Pages read holding an issue or an improvement."},"total":{"type":"integer","title":"Total","description":"The pages read it counts among, coverage.pages_read."},"percent":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Percent"}},"type":"object","required":["count","total","percent"],"title":"V1PagesWithFindings"},"V1PaneAction":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The action or recurring job id."},"tracked_domain_id":{"type":"string","format":"uuid","title":"Tracked Domain Id","description":"Deprecated alias of brand_id.","deprecated":true},"target_entity":{"type":"string","title":"Target Entity","description":"The page, prompt, source or check the work targets."},"write_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Write Language","description":"The writing language code."},"write_language_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Write Language Source","description":"How the language was chosen."},"write_language_locked":{"type":"boolean","title":"Write Language Locked","description":"Whether writing has locked the language.","default":false},"target_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Type","description":"What the target names; null when unknown."},"segment":{"type":"string","title":"Segment","description":"The work's configured segment label."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The act this work proposes or delivers."},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"The finding behind the work; null when absent."},"state":{"type":"string","enum":["new","accepted","in_progress","blocked","looks_resolved","done","verified_no_move","deferred","dismissed","withdrawn"],"title":"State","description":"The action's lifecycle state."},"group":{"type":"string","enum":["new","your_input","dispatched","scheduled","waiting","settled","withdrawn"],"title":"Group","description":"The current work group."},"holder":{"anyOf":[{"type":"string","enum":["you","heralded","waiting"]},{"type":"null"}],"title":"Holder","description":"Who holds the next step; null when nobody does."},"stage":{"type":"string","enum":["observe","decide","do","verify"],"title":"Stage","description":"The work's observe, decide, do or verify stage."},"demand":{"type":"string","title":"Demand","description":"What the work is doing or waiting for."},"member":{"anyOf":[{"type":"string","enum":["writer","publicist","engineer","analyst"]},{"type":"null"}],"title":"Member","description":"The responsible team member; null for setup and prompt replacements."},"waiting_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Waiting Since","description":"When the current ask began; null outside your_input."},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"The first time Heralded started this action. Null on dismissed work."},"delivered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Delivered At","description":"When the result went live, was sent or was published. Null on dismissed work."},"paid_off_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paid Off At","description":"When verification credited a positive measured gain. Null on dismissed work."},"preview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preview","description":"Up to 400 characters of draft opening, email recipient and subject, or planned change while waiting on you."},"outcome":{"anyOf":[{"type":"string","enum":["verified_up","no_move","not_measured","dismissed"]},{"type":"null"}],"title":"Outcome","description":"How settled work ended; null while pending."},"gate":{"anyOf":[{"type":"string","enum":["approval","review"]},{"type":"null"}],"title":"Gate","description":"The review or approval awaited; null otherwise."},"settled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Settled At","description":"When measurement or the decision settled."},"impact_scale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Impact Scale","description":"The measure this action aims to improve."},"expected_impact_pts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expected Impact Pts","description":"Always null: the expected gain is `gain`."},"verified_impact_pts":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Verified Impact Pts","description":"The measured gain credited to the action."},"prompt_movement":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Movement","description":"Whether other work shares the prompt's movement."},"blocked_owner":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blocked Owner","description":"Who the action waits on; null when not blocked."},"check_again_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Check Again On","description":"When to check blocked work again."},"scheduled_for":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Scheduled For","description":"The scheduled start date; null when unset."},"scheduled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Scheduled At","description":"The recurring job's next start."},"repeat":{"anyOf":[{"type":"string","enum":["daily","weekly","thrice_weekly"]},{"type":"null"}],"title":"Repeat","description":"The recurring job's schedule."},"progress":{"anyOf":[{"$ref":"#/components/schemas/WorkProgressResponse"},{"type":"null"}],"description":"The running job's progress."},"platform":{"type":"boolean","title":"Platform","description":"Whether this is Heralded's recurring work.","default":false},"run_state":{"anyOf":[{"type":"string","enum":["scheduled","running","done","skipped","failed","stopped"]},{"type":"null"}],"title":"Run State","description":"The recurring job's current run state."},"assignee":{"anyOf":[{"$ref":"#/components/schemas/AssigneeResponse"},{"type":"null"}],"description":"The person accountable for the work."},"intent_bucket":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent Bucket","description":"The targeted prompt intent; null when absent."},"looks_resolved_evidence":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Looks Resolved Evidence","description":"Evidence for a resolution awaiting confirmation."},"not_seen_since_run":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Not Seen Since Run","description":"The first report that stopped seeing the finding."},"placed_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Placed Position","description":"The member's place in the proposal order."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When the action was marked done."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When this work was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When this work last changed."},"primary_verb":{"anyOf":[{"type":"string","enum":["dispatch","take","done","defer","dismiss","confirm","reject","restore","block","unblock","reopen"]},{"type":"string","const":"review"},{"type":"null"}],"title":"Primary Verb","description":"The main offered action; null when none is offered."},"setup_link":{"anyOf":[{"$ref":"#/components/schemas/SetupLink"},{"type":"null"}],"description":"Where to complete this setup task."},"secondary_verbs":{"items":{"type":"string","enum":["dispatch","take","done","defer","dismiss","confirm","reject","restore","block","unblock","reopen"]},"type":"array","title":"Secondary Verbs","description":"Other offered actions, in menu order."},"return_group":{"anyOf":[{"type":"string","enum":["new","your_input","dispatched","scheduled","waiting","settled","withdrawn"]},{"type":"null"}],"title":"Return Group","description":"The work group a return action resumes."},"job":{"$ref":"#/components/schemas/JobResponse","description":"The work's steps and available controls."},"note":{"anyOf":[{"$ref":"#/components/schemas/TaskNote"},{"type":"null"}],"description":"Task explanation with a live job step."},"credit_cost":{"type":"integer","title":"Credit Cost","description":"Content credits needed to dispatch this work."},"credits_spent":{"type":"integer","title":"Credits Spent","description":"Content credits charged to this work and not refunded."},"dispatchable":{"type":"boolean","title":"Dispatchable","description":"Whether Heralded can execute this work."},"draft_in_flight":{"anyOf":[{"type":"string","enum":["drafting","redrafting"]},{"type":"null"}],"title":"Draft In Flight","description":"Whether a first draft or redraft is being written."},"grounds":{"anyOf":[{"$ref":"#/components/schemas/GroundsResponse"},{"type":"null"}],"description":"What the work rests on; null on Heralded's own work and on work filed before actions carried their grounds."},"done_when":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Done When","description":"When the work is done; null on Heralded's own work."},"tracking":{"items":{"type":"string","enum":["live","crawled","ranked","search_console","cited","moved"]},"type":"array","title":"Tracking","description":"What Heralded tracks once the work is live: live, crawled, ranked, search_console, cited, moved."},"first_citation":{"anyOf":[{"$ref":"#/components/schemas/FirstCitation"},{"type":"null"}],"description":"First qualifying citation of the delivered page."},"citation_count":{"type":"integer","title":"Citation Count","description":"Distinct engine and prompt citation pairs before the list cap.","default":0},"gain":{"anyOf":[{"$ref":"#/components/schemas/GainResponse"},{"type":"null"}],"description":"The expected gain: its band and what the work aims at. Null on Heralded's own work."},"focus":{"anyOf":[{"$ref":"#/components/schemas/FocusTag"},{"type":"null"}],"description":"The starred topic or competitor the work serves, or outside your focus. Null when the brand has no starred topic or competitor, and on Heralded's own work."},"kind_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind Tag","description":"A tag on the kind of work, shown beside its state, such as Sponsored. Null on work that has none."},"ending":{"anyOf":[{"$ref":"#/components/schemas/EndingResponse"},{"type":"null"}],"description":"How the task ended: its key, its words and when. Null while it is open."},"wait":{"anyOf":[{"$ref":"#/components/schemas/WaitResponse"},{"type":"null"}],"description":"What the task waits for, on whom and until when. Null while it waits on nobody."},"brand_id":{"type":"string","format":"uuid","title":"Brand Id","description":"The brand this work belongs to.","readOnly":true},"route":{"type":"string","enum":["home","actions","prompts","search","market","sources","content","perception","audit"],"title":"Route","description":"The Command Center page this work concerns.","readOnly":true},"kind":{"type":"string","title":"Kind","readOnly":true}},"type":"object","required":["id","tracked_domain_id","target_entity","write_language","write_language_source","write_language_locked","target_type","segment","title","detail","state","group","holder","stage","demand","member","waiting_since","started_at","delivered_at","paid_off_at","preview","outcome","gate","settled_at","impact_scale","expected_impact_pts","verified_impact_pts","prompt_movement","blocked_owner","check_again_on","scheduled_for","scheduled_at","repeat","progress","platform","run_state","assignee","intent_bucket","looks_resolved_evidence","not_seen_since_run","placed_position","completed_at","created_at","updated_at","primary_verb","setup_link","secondary_verbs","return_group","job","note","credit_cost","credits_spent","dispatchable","draft_in_flight","grounds","done_when","tracking","first_citation","citation_count","gain","focus","kind_tag","ending","wait","brand_id","route","kind"],"title":"V1PaneAction"},"V1Perception":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headline","description":"Written statement or templated sentence over served figures; null when Understood has no measured value."},"facts_summary":{"$ref":"#/components/schemas/FactSummary","description":"Mostly-right and measured fact counts, plus fact keys with insufficient addressing answers."},"domain":{"type":"string","title":"Domain"},"period":{"$ref":"#/components/schemas/V1Period"},"filters":{"$ref":"#/components/schemas/FigureFilters"},"written":{"$ref":"#/components/schemas/V1PerceptionWrittenPieces"},"understood":{"$ref":"#/components/schemas/V1Figure","description":"0.63 × the AI part + 0.37 × the web part; the AI part alone under ten documents or a filter."},"praised":{"$ref":"#/components/schemas/V1Figure"},"claims":{"items":{"$ref":"#/components/schemas/V1PerceptionClaimRow"},"type":"array","title":"Claims"},"negative_prompts":{"items":{"$ref":"#/components/schemas/V1PerceptionNegativePrompt"},"type":"array","title":"Negative Prompts"},"negative_sources":{"items":{"$ref":"#/components/schemas/V1PerceptionNegativeSource"},"type":"array","title":"Negative Sources"},"negative_prompts_total":{"type":"integer","title":"Negative Prompts Total","description":"All prompts with negative evidence before paging."},"negative_sources_total":{"type":"integer","title":"Negative Sources Total","description":"All sources with negative evidence before paging."},"best_quotes":{"items":{"$ref":"#/components/schemas/V1PerceptionBestQuote"},"type":"array","title":"Best Quotes"}},"type":"object","required":["meta","headline","facts_summary","domain","period","filters","written","understood","praised","claims","negative_prompts","negative_sources","negative_prompts_total","negative_sources_total","best_quotes"],"title":"V1Perception"},"V1PerceptionBestQuote":{"properties":{"asked_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asked Language"},"language":{"type":"string","title":"Language","default":"unknown"},"quote":{"type":"string","title":"Quote"},"engine_id":{"type":"string","title":"Engine Id"},"prompt_uid":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Prompt Uid"},"prompt_text":{"type":"string","title":"Prompt Text"},"answer_read_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Answer Read Id"}},"type":"object","required":["asked_language","language","quote","engine_id","prompt_uid","prompt_text","answer_read_id"],"title":"V1PerceptionBestQuote"},"V1PerceptionClaim":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"definition":{"anyOf":[{"$ref":"#/components/schemas/BrandFact"},{"type":"null"}],"description":"The current member-added fact and its original author. Null for a profile claim."},"next_fact_check_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Fact Check At","description":"The brand's next weekly report date, when scheduled."},"brand_paused":{"type":"boolean","title":"Brand Paused","description":"Whether the brand's checks are paused.","default":false},"period":{"$ref":"#/components/schemas/V1Period"},"filters":{"$ref":"#/components/schemas/FigureFilters"},"claim":{"$ref":"#/components/schemas/V1PerceptionClaimRow"},"added_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Added At"},"quotes":{"items":{"$ref":"#/components/schemas/V1PerceptionQuotedLine"},"type":"array","title":"Quotes"},"prompts":{"items":{"$ref":"#/components/schemas/V1PerceptionClaimPrompt"},"type":"array","title":"Prompts"},"engines":{"items":{"$ref":"#/components/schemas/V1PerceptionClaimEngine"},"type":"array","title":"Engines"},"pages":{"items":{"$ref":"#/components/schemas/V1PerceptionContradictingPage"},"type":"array","title":"Pages"},"prompts_total":{"type":"integer","title":"Prompts Total","description":"All prompts matching this selection before paging."},"pages_total":{"type":"integer","title":"Pages Total","description":"All pages under the selected filters before paging."},"answers_link":{"$ref":"#/components/schemas/AnswersLink"}},"type":"object","required":["meta","definition","next_fact_check_at","brand_paused","period","filters","claim","added_at","quotes","prompts","engines","pages","prompts_total","pages_total","answers_link"],"title":"V1PerceptionClaim"},"V1PerceptionClaimEngine":{"properties":{"engine_id":{"type":"string","title":"Engine Id"},"contradicts":{"type":"integer","title":"Contradicts"},"answers":{"type":"integer","title":"Answers"}},"type":"object","required":["engine_id","contradicts","answers"],"title":"V1PerceptionClaimEngine"},"V1PerceptionClaimPrompt":{"properties":{"prompt_uid":{"type":"string","format":"uuid","title":"Prompt Uid"},"text":{"type":"string","title":"Text"},"contradicts":{"type":"integer","title":"Contradicts"}},"type":"object","required":["prompt_uid","text","contradicts"],"title":"V1PerceptionClaimPrompt"},"V1PerceptionClaimRow":{"properties":{"insight":{"anyOf":[{"$ref":"#/components/schemas/ServedInsight"},{"type":"null"}],"description":"Recommended page insight, when the read serves one."},"key":{"type":"string","title":"Key"},"kind":{"type":"string","enum":["category","audience","offer","difference","fact"],"title":"Kind"},"wording":{"type":"string","title":"Wording"},"quote":{"anyOf":[{"$ref":"#/components/schemas/V1PerceptionQuotedLine"},{"type":"null"}]},"verdicts":{"$ref":"#/components/schemas/V1PerceptionVerdicts"},"origins":{"anyOf":[{"$ref":"#/components/schemas/V1FactOrigins"},{"type":"null"}],"description":"A fact's verdict counts split by origin: its own question (`probe`) or tracked prompts that name the brand (`prompt`). Null for a profile claim."},"definition_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Definition Version","description":"The fact definition version the counts were read against; null for a profile claim or for readings from before definitions were versioned."},"current_version_pending":{"type":"boolean","title":"Current Version Pending","description":"The fact was edited to a new definition no report has read yet; the counts are of `definition_version`.","default":false},"trend":{"$ref":"#/components/schemas/V1PerceptionClaimTrend"},"state":{"anyOf":[{"$ref":"#/components/schemas/V1PerceptionClaimState"},{"type":"null"}]},"parts":{"items":{"$ref":"#/components/schemas/V1PerceptionStatementPart"},"type":"array","title":"Parts","description":"A profile statement's parts, where the latest report measured Understood part by part; empty for a fact or a statement measured whole."}},"type":"object","required":["insight","key","kind","wording","quote","verdicts","origins","definition_version","current_version_pending","trend","state","parts"],"title":"V1PerceptionClaimRow"},"V1PerceptionClaimState":{"properties":{"kind":{"type":"string","enum":["new","action","resolved"],"title":"Kind"},"label":{"type":"string","title":"Label"},"action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Action Id"}},"type":"object","required":["kind","label","action_id"],"title":"V1PerceptionClaimState"},"V1PerceptionClaimTrend":{"properties":{"state":{"type":"string","enum":["up","down","steady","calibrating","first_report","not_comparable","none"],"title":"State"},"delta":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Delta"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"definition_changed":{"type":"boolean","title":"Definition Changed","description":"The comparison crosses an edit that changed the fact's meaning, so no change is shown across it.","default":false}},"type":"object","required":["state","delta","label","definition_changed"],"title":"V1PerceptionClaimTrend","description":"The change in the share of answers that contradict a claim, as the\nTrend column states it: a rise is bad."},"V1PerceptionContradictingPage":{"properties":{"language":{"type":"string","title":"Language","default":"unknown"},"url":{"type":"string","title":"Url"},"domain":{"type":"string","title":"Domain"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"passage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Passage"},"wording":{"type":"string","title":"Wording"},"citations":{"type":"integer","title":"Citations"},"owned":{"type":"boolean","title":"Owned"},"state":{"anyOf":[{"$ref":"#/components/schemas/V1PerceptionPageState"},{"type":"null"}]},"insight":{"anyOf":[{"$ref":"#/components/schemas/ServedInsight"},{"type":"null"}],"description":"The work that fits the page, a fix of your own page or a correction request to a third-party one, and the work filed from it."}},"type":"object","required":["language","url","domain","title","type","passage","wording","citations","owned","state","insight"],"title":"V1PerceptionContradictingPage"},"V1PerceptionNegativePrompt":{"properties":{"prompt_uid":{"type":"string","format":"uuid","title":"Prompt Uid"},"text":{"type":"string","title":"Text"},"negative":{"type":"integer","title":"Negative"},"answers":{"type":"integer","title":"Answers"},"state":{"type":"string","enum":["measured","too_few_answers"],"title":"State"},"share":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Share"}},"type":"object","required":["prompt_uid","text","negative","answers","state","share"],"title":"V1PerceptionNegativePrompt"},"V1PerceptionNegativeSource":{"properties":{"domain_citations":{"type":"integer","title":"Domain Citations","description":"Citations of this domain under the read filters.","default":0},"language":{"type":"string","title":"Language","default":"unknown"},"url":{"type":"string","title":"Url"},"domain":{"type":"string","title":"Domain"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"passage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Passage"},"citations":{"type":"integer","title":"Citations"},"state":{"anyOf":[{"$ref":"#/components/schemas/V1PerceptionPageState"},{"type":"null"}]}},"type":"object","required":["domain_citations","language","url","domain","title","type","passage","citations","state"],"title":"V1PerceptionNegativeSource"},"V1PerceptionPageState":{"properties":{"kind":{"type":"string","enum":["new","action","yours"],"title":"Kind"},"label":{"type":"string","title":"Label"},"action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Action Id"}},"type":"object","required":["kind","label","action_id"],"title":"V1PerceptionPageState"},"V1PerceptionPositioningCell":{"properties":{"brand_key":{"type":"string","title":"Brand Key"},"name":{"type":"string","title":"Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"is_you":{"type":"boolean","title":"Is You"},"engines":{"type":"integer","title":"Engines"},"line":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Line"}},"type":"object","required":["brand_key","name","domain","is_you","engines","line"],"title":"V1PerceptionPositioningCell"},"V1PerceptionQuotedLine":{"properties":{"verdict":{"type":"string","enum":["agrees","partly","contradicts","doesnt_say"],"title":"Verdict"},"quote":{"type":"string","title":"Quote"},"count":{"type":"integer","title":"Count"},"engine_id":{"type":"string","title":"Engine Id"},"prompt_uid":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Prompt Uid"},"answer_read_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Answer Read Id"},"asked_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asked Language"},"language":{"type":"string","title":"Language","default":"unknown"}},"type":"object","required":["verdict","quote","count","engine_id","prompt_uid","answer_read_id","asked_language","language"],"title":"V1PerceptionQuotedLine","description":"One answer's words on a claim, and how many answers reached its verdict."},"V1PerceptionStatementPart":{"properties":{"key":{"type":"string","title":"Key","description":"The part's stable key, kept across rewordings of its meaning."},"wording":{"type":"string","title":"Wording","description":"The part as the latest report measured it."},"quote":{"anyOf":[{"$ref":"#/components/schemas/V1PerceptionQuotedLine"},{"type":"null"}],"description":"An answer's words on the part, contradicting first; null where no answer quotes it."},"verdicts":{"$ref":"#/components/schemas/V1PerceptionVerdicts","description":"Answers naming the brand by verdict; `doesnt_say` counts those that never mention the part, which leave it out of their Understood."},"trend":{"$ref":"#/components/schemas/V1PerceptionClaimTrend","description":"The change in the share of answers contradicting it; no change is called across a change in how Understood was measured."}},"type":"object","required":["key","wording","quote","verdicts","trend"],"title":"V1PerceptionStatementPart","description":"One part of a profile statement, as the latest report measured it."},"V1PerceptionVerdicts":{"properties":{"agrees":{"type":"integer","title":"Agrees","default":0},"partly":{"type":"integer","title":"Partly","default":0},"contradicts":{"type":"integer","title":"Contradicts","default":0},"doesnt_say":{"type":"integer","title":"Doesnt Say","default":0},"answers":{"type":"integer","title":"Answers","default":0}},"type":"object","required":["agrees","partly","contradicts","doesnt_say","answers"],"title":"V1PerceptionVerdicts"},"V1PerceptionWrittenPieces":{"properties":{"report_scan_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Report Scan Id"},"report_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Report At"},"statement":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Statement"},"line_to_own":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Line To Own"},"positioning":{"items":{"$ref":"#/components/schemas/V1PerceptionPositioningCell"},"type":"array","title":"Positioning"}},"type":"object","required":["report_scan_id","report_at","statement","line_to_own","positioning"],"title":"V1PerceptionWrittenPieces","description":"What the latest weekly report's interpretation wrote, over every\nanswer and every engine: none of it follows the period or a filter."},"V1Period":{"properties":{"preset":{"type":"string","enum":["1w","4w","12w","all"],"title":"Preset"},"reports":{"type":"integer","title":"Reports"},"first_answer_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Answer At"},"last_answer_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Answer At"},"excluded_reports":{"type":"integer","title":"Excluded Reports"}},"type":"object","required":["preset","reports","first_answer_at","last_answer_at","excluded_reports"],"title":"V1Period"},"V1Portfolio":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"kind":{"type":"string","const":"organization","title":"Kind","description":"Direct organization portfolio.","default":"organization"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"brands":{"items":{"$ref":"#/components/schemas/PortfolioBrandRow"},"type":"array","title":"Brands"}},"type":"object","required":["meta","next_cursor","total","limit","offset","kind","organization_id","brands"],"title":"V1Portfolio","examples":[{"brands":[],"kind":"organization","limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"organization_id":"00000000-0000-4000-8000-000000000001","total":0}]},"V1ProductData":{"properties":{"state":{"type":"string","enum":["complete","incomplete","unreadable","not_checked"],"title":"State","description":"complete: the page states every required field; incomplete: it misses one; unreadable: its page could not be read; not_checked: not in the checked sample."},"missing":{"items":{"type":"string"},"type":"array","title":"Missing","description":"The required fields its page does not state."},"failing":{"items":{"type":"string"},"type":"array","title":"Failing","description":"Every check its page fails, by check id."}},"type":"object","required":["state","missing","failing"],"title":"V1ProductData"},"V1ProductDetail":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"period":{"$ref":"#/components/schemas/V1Period","description":"The weekly reports the figures cover."},"cards_read":{"type":"boolean","title":"Cards Read","description":"Whether any answer under the period and filters had its product cards read. False means its figures are unmeasured, not zero."},"product":{"$ref":"#/components/schemas/V1ProductRow","description":"The product and its figures."},"trend":{"items":{"$ref":"#/components/schemas/V1ProductTrendPoint"},"type":"array","title":"Trend","description":"One point per weekly report, oldest first."},"engines":{"items":{"$ref":"#/components/schemas/ShoppingProductEngine"},"type":"array","title":"Engines","description":"The product's figures per engine."},"questions":{"items":{"$ref":"#/components/schemas/ShoppingQuestion"},"type":"array","title":"Questions","description":"One page of its questions."},"questions_total":{"type":"integer","title":"Questions Total","description":"Its questions before paging."},"questions_limit":{"type":"integer","title":"Questions Limit","description":"Questions per page."},"questions_offset":{"type":"integer","title":"Questions Offset","description":"Questions skipped."},"shown_instead":{"items":{"$ref":"#/components/schemas/V1ProductRow"},"type":"array","title":"Shown Instead","description":"One page of rival products shown in the same filtered answer population."},"shown_instead_total":{"type":"integer","title":"Shown Instead Total","description":"Rival products shown before paging."},"shown_instead_limit":{"type":"integer","title":"Shown Instead Limit","description":"Products shown beside it per page."},"shown_instead_offset":{"type":"integer","title":"Shown Instead Offset","description":"Products shown beside it skipped."},"facts":{"items":{"$ref":"#/components/schemas/V1ProductFact"},"type":"array","title":"Facts","description":"What answers state about it, most stated first."},"sources":{"items":{"$ref":"#/components/schemas/V1ProductSource"},"type":"array","title":"Sources","description":"One page of the pages cited beside it."},"sources_total":{"type":"integer","title":"Sources Total","description":"Cited pages before paging."},"sources_limit":{"type":"integer","title":"Sources Limit","description":"Cited pages per page."},"sources_offset":{"type":"integer","title":"Sources Offset","description":"Cited pages skipped."},"revenue":{"anyOf":[{"items":{"$ref":"#/components/schemas/V1AssistantRevenue"},"type":"array"},{"type":"null"}],"title":"Revenue","description":"Its revenue from AI by assistant; null without revenue split by product."},"actions":{"items":{"$ref":"#/components/schemas/V1PaneAction"},"type":"array","title":"Actions","description":"The live actions about the product's page, highest priority first."},"actions_total":{"type":"integer","title":"Actions Total","description":"Live actions about its page."},"next_step":{"anyOf":[{"$ref":"#/components/schemas/V1PaneAction"},{"type":"null"}],"description":"The action to start next, if any."},"insight":{"anyOf":[{"$ref":"#/components/schemas/ServedInsight"},{"type":"null"}],"description":"Work on this: the kinds of work that fit your product, its page rewrite, its product markup and a retailer to be listed with, and the work already filed from it. Null for a product shown instead of yours."}},"type":"object","required":["meta","period","cards_read","product","trend","engines","questions","questions_total","questions_limit","questions_offset","shown_instead","shown_instead_total","shown_instead_limit","shown_instead_offset","facts","sources","sources_total","sources_limit","sources_offset","revenue","actions","actions_total","next_step","insight"],"title":"V1ProductDetail","description":"One product: its figures, trend, engines, questions, the products shown instead,\nwhat answers state about it, the pages they cite, its readiness, revenue and work."},"V1ProductFact":{"properties":{"text":{"type":"string","title":"Text","description":"What an answer states about the product."},"answers":{"type":"integer","title":"Answers","description":"Answers stating it."}},"type":"object","required":["text","answers"],"title":"V1ProductFact"},"V1ProductReadiness":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total","description":"Rows of this list under these filters, before paging."},"limit":{"type":"integer","title":"Limit","description":"The page's maximum rows."},"offset":{"type":"integer","title":"Offset","description":"Rows skipped before this page."},"period":{"$ref":"#/components/schemas/V1Period","description":"The weekly reports the read comes from."},"scan_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Scan Id","description":"The report whose catalogue read this is."},"catalogue":{"anyOf":[{"$ref":"#/components/schemas/ShoppingCatalogueRead"},{"type":"null"}],"description":"The read's outcome and complete product data; null without a read."},"stages":{"items":{"$ref":"#/components/schemas/ShoppingStage"},"type":"array","title":"Stages","description":"The four stages, in order."},"checks":{"items":{"$ref":"#/components/schemas/ShoppingCheck"},"type":"array","title":"Checks","description":"One page of checks."}},"type":"object","required":["meta","next_cursor","total","limit","offset","period","scan_id","catalogue","stages","checks"],"title":"V1ProductReadiness","description":"How the products checked in the newest catalogue read meet Google's and OpenAI's\nproduct data standards.","examples":[{"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"total":0,"limit":20,"offset":0,"period":{"preset":"1w","reports":1,"first_answer_at":null,"last_answer_at":null,"excluded_reports":0},"scan_id":null,"catalogue":null,"stages":[],"checks":[]}]},"V1ProductRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The product's id."},"name":{"type":"string","title":"Name","description":"Your catalogue's title, else the name its cards showed."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The maker's own page for the product."},"yours":{"type":"boolean","title":"Yours","description":"The product is one of your brand's."},"maker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Maker","description":"A rival product's maker brand, where judged."},"shown":{"$ref":"#/components/schemas/ShoppingShare","description":"Answers showing this product divided by all answers with organic product cards, using the pooled answer ratio and interval."},"answers_shown":{"type":"integer","title":"Answers Shown","description":"Answers showing it in an organic card, on any topic."},"average_position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Position","description":"Its mean best organic place among the cards, when shown."},"best_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Position","description":"Its lowest organic card place across counted answers."},"seller_is_your_shop":{"anyOf":[{"$ref":"#/components/schemas/ShoppingShare"},{"type":"null"}],"description":"Its appearances naming your shop as the seller; null for a rival's."},"price_matches_your_shop":{"anyOf":[{"$ref":"#/components/schemas/ShoppingShare"},{"type":"null"}],"description":"Its appearances sold by your shop whose price matched; null for a rival's."},"offer":{"anyOf":[{"$ref":"#/components/schemas/ShoppingOffer"},{"type":"null"}],"description":"The newest card that showed it; null if none."},"product_data":{"$ref":"#/components/schemas/V1ProductData","description":"Its page against Google's and OpenAI's required fields."},"questions_shown":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Questions Shown","description":"Distinct questions whose read answers showed this product; null for B2B."},"ai_revenue":{"anyOf":[{"$ref":"#/components/schemas/V1Revenue"},{"type":"null"}],"description":"Revenue from AI for the product; null without revenue split by product."}},"type":"object","required":["id","name","url","yours","maker","shown","answers_shown","average_position","best_position","seller_is_your_shop","price_matches_your_shop","offer","product_data","questions_shown","ai_revenue"],"title":"V1ProductRow","description":"One of your products, or one shown instead, as the Products list shows it."},"V1ProductSeller":{"properties":{"name":{"type":"string","title":"Name","description":"The seller as the cards displayed it."},"your_shop":{"type":"boolean","title":"Your Shop","description":"The seller is your own shop."},"marketplace":{"type":"boolean","title":"Marketplace","description":"A card named it as a marketplace."},"products_shown":{"type":"integer","title":"Products Shown","description":"Product appearances it was shown selling."},"yours":{"type":"integer","title":"Yours","description":"Of those, your products."},"share_of_yours":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Share Of Yours","description":"Your products' share of its appearances; null when it showed none."}},"type":"object","required":["name","your_shop","marketplace","products_shown","yours","share_of_yours"],"title":"V1ProductSeller"},"V1ProductSellers":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total","description":"Rows of this list under these filters, before paging."},"limit":{"type":"integer","title":"Limit","description":"The page's maximum rows."},"offset":{"type":"integer","title":"Offset","description":"Rows skipped before this page."},"period":{"$ref":"#/components/schemas/V1Period","description":"The weekly reports the sellers come from."},"sellers":{"items":{"$ref":"#/components/schemas/V1ProductSeller"},"type":"array","title":"Sellers","description":"One page of sellers."}},"type":"object","required":["meta","next_cursor","total","limit","offset","period","sellers"],"title":"V1ProductSellers","description":"The sellers AI shopping cards named on your questions.","examples":[{"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"total":0,"limit":20,"offset":0,"period":{"preset":"1w","reports":1,"first_answer_at":null,"last_answer_at":null,"excluded_reports":0},"sellers":[]}]},"V1ProductSource":{"properties":{"domain":{"type":"string","title":"Domain","description":"The cited page's site."},"url":{"type":"string","title":"Url","description":"The cited page."},"answers":{"type":"integer","title":"Answers","description":"Answers showing the product that cited it."}},"type":"object","required":["domain","url","answers"],"title":"V1ProductSource"},"V1ProductTrendPoint":{"properties":{"scan_id":{"type":"string","format":"uuid","title":"Scan Id","description":"The weekly report."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When the report completed."},"shown":{"$ref":"#/components/schemas/ShoppingShare","description":"The product's Shown share in that report."},"average_position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Position","description":"Its average position in that report."}},"type":"object","required":["scan_id","completed_at","shown","average_position"],"title":"V1ProductTrendPoint"},"V1Products":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total","description":"Rows of this list under these filters, before paging."},"limit":{"type":"integer","title":"Limit","description":"The page's maximum rows."},"offset":{"type":"integer","title":"Offset","description":"Rows skipped before this page."},"period":{"$ref":"#/components/schemas/V1Period","description":"The weekly reports the figures cover."},"question_strip":{"anyOf":[{"$ref":"#/components/schemas/ProductQuestionStrip"},{"type":"null"}],"description":"Unbranded tracked questions under the page's figure filters; null for B2B."},"engines":{"anyOf":[{"items":{"$ref":"#/components/schemas/ProductCardEngine"},"type":"array"},{"type":"null"}],"title":"Engines","description":"Questions with cards and yours, in served engine order; null for B2B."},"rank":{"anyOf":[{"$ref":"#/components/schemas/ProductCardRank"},{"type":"null"}],"description":"Place by In product cards among you and tracked competitors, with ties; null without cards or for B2B."},"figures":{"anyOf":[{"$ref":"#/components/schemas/ShoppingCardFigures"},{"type":"null"}],"description":"Product card figures; null where no report in the period read cards."},"catalogue":{"anyOf":[{"$ref":"#/components/schemas/ShoppingCatalogueRead"},{"type":"null"}],"description":"The newest catalogue read in the period and its complete product data; null without one."},"revenue":{"anyOf":[{"$ref":"#/components/schemas/V1RevenueFromAi"},{"type":"null"}],"description":"Revenue from AI from Google Analytics; null without a whole read of a property tracking purchases, never zero."},"products":{"items":{"$ref":"#/components/schemas/V1ProductRow"},"type":"array","title":"Products","description":"One page of products under the view and filters."},"product_card_weeks":{"type":"integer","title":"Product Card Weeks","description":"Weekly reports in the period measured as ecommerce.","default":0},"maker_options":{"anyOf":[{"items":{"$ref":"#/components/schemas/VocabularyOption"},"type":"array"},{"type":"null"}],"title":"Maker Options","description":"Paged canonical maker keys and names with with_makers=true."},"maker_options_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Maker Options Total","description":"Available makers before maker-option paging; null when not requested."}},"type":"object","required":["meta","next_cursor","total","limit","offset","period","question_strip","engines","rank","figures","catalogue","revenue","products","product_card_weeks","maker_options","maker_options_total"],"title":"V1Products","description":"Products in AI shopping answers, with the period's figures.","examples":[{"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"total":0,"limit":20,"offset":0,"period":{"preset":"1w","reports":1,"first_answer_at":null,"last_answer_at":null,"excluded_reports":0},"figures":null,"catalogue":null,"revenue":null,"products":[],"product_card_weeks":0,"maker_options":null,"maker_options_total":null,"question_strip":null,"engines":null,"rank":null}]},"V1Prompt":{"properties":{"market":{"type":"string","title":"Market","description":"The topic's market: country ISO code, europe or global.","default":"global"},"audience":{"type":"string","title":"Audience","description":"The topic's audience name.","default":"All buyers"},"audience_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Audience Id","description":"Audience UUID; null for All buyers."},"measurement_status":{"type":"string","enum":["new","measured"],"title":"Measurement Status","description":"New until a subscription weekly report scores it, then measured. Independent of tracking state.","default":"new"},"first_answers_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Answers At","description":"The first answered time, or the estimate while its prompt read is pending. Null when no estimate is available."},"first_score_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"First Score On","description":"The next weekly report's date for the market. Null before the brand has a weekly schedule."},"evidence":{"items":{"$ref":"#/components/schemas/V1TopicEvidence"},"type":"array","title":"Evidence","description":"The stored evidence behind the prompt: the buyer phrasing it was drafted from, then the questions members added to its topic, which feed the topic's next draft. Empty when nothing was recorded."},"synthesised":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Synthesised","description":"True when Heralded wrote the prompt with no buyer evidence behind it; null when it was written before drafts recorded their evidence, or by a member."},"product_cards":{"anyOf":[{"$ref":"#/components/schemas/ProductCardsCell"},{"type":"null"}],"description":"Product-card figures for ecommerce brands; null for other brands and Google search."},"tracked_topic_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tracked Topic Id","description":"Tracked-topic UUID."},"insight":{"anyOf":[{"$ref":"#/components/schemas/ServedInsight"},{"type":"null"}],"description":"Where an engine's latest answer leaves you out: the piece that fits the question and the content work filed for it."},"languages":{"items":{"type":"string"},"type":"array","title":"Languages"},"master_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Master Version"},"wordings":{"items":{"$ref":"#/components/schemas/V1PromptWording"},"type":"array","title":"Wordings","description":"Latest stored asked wording per country and language, plus older wordings with different text asked in the selected period. An older version with the same text is folded into the newer one, whose counts include its answers. Counts are distinct rendered answers and answers naming the brand under the period and figure filters. Empty for prompts with no stored wordings; no per-country score is issued."},"measurement":{"anyOf":[{"$ref":"#/components/schemas/KeywordMeasurement"},{"type":"null"}]},"id":{"type":"string","format":"uuid","title":"Id"},"text":{"type":"string","title":"Text"},"status":{"type":"string","enum":["active","paused","archived"],"title":"Status"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topic"},"intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent"},"engines":{"items":{"$ref":"#/components/schemas/V1PromptEngine"},"type":"array","title":"Engines"},"status_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Status Since"},"prompt_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Type"},"search_volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Volume"},"change":{"anyOf":[{"$ref":"#/components/schemas/PromptChange"},{"type":"null"}]},"score":{"anyOf":[{"$ref":"#/components/schemas/ScoreMark"},{"type":"null"}]},"trend":{"anyOf":[{"$ref":"#/components/schemas/PromptTrend"},{"type":"null"}]},"marks":{"items":{"$ref":"#/components/schemas/ScoreMark"},"type":"array","title":"Marks"},"cells":{"items":{"$ref":"#/components/schemas/PromptCell"},"type":"array","title":"Cells"},"low_signal":{"type":"boolean","title":"Low Signal","description":"A comparison or transactional prompt whose answers rarely name any company; its `health` is on the prompt's own read.","default":false},"ai_searches":{"items":{"$ref":"#/components/schemas/V1AISearch"},"type":"array","title":"Ai Searches","description":"Observed engine searches tied to this prompt's dated answers. Leads for Google-rank checks, never buyer evidence or page-coverage questions. Empty when no retained answer exposes searches."}},"type":"object","required":["market","audience","audience_id","measurement_status","first_answers_at","first_score_on","evidence","synthesised","product_cards","tracked_topic_id","insight","languages","master_version","wordings","measurement","id","text","status","topic","intent","engines","status_since","prompt_type","search_volume","change","score","trend","marks","cells","low_signal","ai_searches"],"title":"V1Prompt"},"V1PromptAction":{"properties":{"waiting_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Waiting Since","description":"When the current ask began; null outside your_input."},"route":{"type":"string","title":"Route"},"demand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Demand","description":"What the current work asks of you."},"first_citation":{"anyOf":[{"$ref":"#/components/schemas/FirstCitation"},{"type":"null"}],"description":"First qualifying citation of the delivered page."},"citation_count":{"type":"integer","title":"Citation Count","description":"Distinct engine and prompt citation pairs before the list cap.","default":0},"write_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Write Language"},"write_language_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Write Language Source"},"write_language_locked":{"type":"boolean","title":"Write Language Locked","default":false},"placed_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Placed Position","description":"Position in the brand's proposed order; null when Heralded ranks it."},"not_seen_since_run":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Not Seen Since Run","description":"First read that stopped seeing this suggestion; null when seen."},"evidence":{"anyOf":[{"$ref":"#/components/schemas/TaskEvidence"},{"type":"null"}],"description":"Linked prompts and rendered answer counts from the latest report."},"note":{"anyOf":[{"$ref":"#/components/schemas/TaskNote"},{"type":"null"}],"description":"Task explanation with a live job step."},"id":{"type":"string","format":"uuid","title":"Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"},"kind":{"type":"string","title":"Kind"},"member":{"anyOf":[{"type":"string","enum":["writer","publicist","engineer","analyst"]},{"type":"null"}],"title":"Member","description":"The responsible team member; null for setup and prompt replacements."},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"The action's first start by Heralded; null on dismissed work."},"delivered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Delivered At","description":"When the result went live, was sent or was published; null on dismissed work."},"paid_off_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paid Off At","description":"When verification credited a positive measured gain; null on dismissed work."},"preview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preview","description":"Up to 400 characters of draft opening, email recipient and subject, or planned change while waiting on you."},"group":{"type":"string","enum":["new","your_input","dispatched","scheduled","waiting","settled","withdrawn"],"title":"Group"},"scheduled_for":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Scheduled For","description":"The scheduled action's start date; null when the action is not scheduled."},"holder":{"anyOf":[{"type":"string","enum":["you","heralded","waiting"]},{"type":"null"}],"title":"Holder","description":"Who holds the work: you, Heralded or a third party; null when nobody holds it."},"stage":{"type":"string","enum":["observe","decide","do","verify"],"title":"Stage","description":"The work's stage: observe, decide, do or verify."},"outcome":{"anyOf":[{"type":"string","enum":["verified_up","no_move","not_measured","dismissed"]},{"type":"null"}],"title":"Outcome"},"grounds":{"anyOf":[{"$ref":"#/components/schemas/GroundsResponse"},{"type":"null"}],"description":"What the work rests on: its kind, its likely cause, the dated evidence, the prompt or keyword results it targets and, for best practice, the publisher guidance. Null on work filed before actions carried their grounds."},"done_when":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Done When","description":"When the work is done."},"tracking":{"items":{"type":"string","enum":["live","crawled","ranked","search_console","cited","moved"]},"type":"array","title":"Tracking","description":"What Heralded tracks once the work is live."},"gain":{"anyOf":[{"$ref":"#/components/schemas/GainResponse"},{"type":"null"}],"description":"The expected gain: its band (high, medium or low, null on work you asked for) and what the work aims at."},"focus":{"anyOf":[{"$ref":"#/components/schemas/FocusTag"},{"type":"null"}],"description":"The starred topic or competitor the work serves, or outside your focus."},"kind_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind Tag","description":"A tag on the kind of work, such as Sponsored; null on work that has none."},"ending":{"anyOf":[{"$ref":"#/components/schemas/EndingResponse"},{"type":"null"}],"description":"How the task ended, such as No reply, Stopped or Not relevant, and when; null while it is open. `outcome` keeps its meaning."},"wait":{"anyOf":[{"$ref":"#/components/schemas/WaitResponse"},{"type":"null"}],"description":"What the task waits for, on whom, until when and who acts then; null while it waits on nobody."},"created_at":{"type":"string","format":"date-time","title":"Created At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"},"state":{"type":"string","enum":["new","accepted","in_progress","blocked","looks_resolved","done","verified_no_move","deferred","dismissed","withdrawn"],"title":"State"},"target_entity":{"type":"string","title":"Target Entity"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"impact_scale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Impact Scale"},"expected_impact_pts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expected Impact Pts","description":"Always null: the expected gain is `gain`."},"verified_impact_pts":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Verified Impact Pts"},"primary_verb":{"anyOf":[{"type":"string","enum":["dispatch","take","done","defer","dismiss","confirm","reject","restore","block","unblock","reopen"]},{"type":"string","const":"review"},{"type":"null"}],"title":"Primary Verb"},"secondary_verbs":{"items":{"type":"string","enum":["dispatch","take","done","defer","dismiss","confirm","reject","restore","block","unblock","reopen"]},"type":"array","title":"Secondary Verbs"},"job":{"$ref":"#/components/schemas/JobResponse"},"credit_cost":{"type":"integer","title":"Credit Cost"},"credits_spent":{"type":"integer","title":"Credits Spent","description":"Content credits charged to this work and not refunded."},"dispatchable":{"type":"boolean","title":"Dispatchable"},"platform":{"type":"boolean","title":"Platform"},"gate":{"anyOf":[{"type":"string","enum":["approval","review"]},{"type":"null"}],"title":"Gate"},"setup_link":{"anyOf":[{"$ref":"#/components/schemas/SetupLink"},{"type":"null"}]},"return_group":{"anyOf":[{"type":"string","enum":["new","your_input","dispatched","scheduled","waiting","settled","withdrawn"]},{"type":"null"}],"title":"Return Group"},"draft_in_flight":{"anyOf":[{"type":"string","enum":["drafting","redrafting"]},{"type":"null"}],"title":"Draft In Flight"}},"type":"object","required":["waiting_since","route","demand","first_citation","citation_count","write_language","write_language_source","write_language_locked","placed_position","not_seen_since_run","evidence","note","id","title","detail","kind","member","started_at","delivered_at","paid_off_at","preview","group","scheduled_for","holder","stage","outcome","grounds","done_when","tracking","gain","focus","kind_tag","ending","wait","created_at","completed_at","state","target_entity","updated_at","impact_scale","expected_impact_pts","verified_impact_pts","primary_verb","secondary_verbs","job","credit_cost","credits_spent","dispatchable","platform","gate","setup_link","return_group","draft_in_flight"],"title":"V1PromptAction"},"V1PromptCompetitor":{"properties":{"key":{"type":"string","title":"Key"},"name":{"type":"string","title":"Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"is_you":{"type":"boolean","title":"Is You"},"heralded_score":{"$ref":"#/components/schemas/V1Figure"},"mentioned":{"$ref":"#/components/schemas/V1Figure"},"recommended":{"$ref":"#/components/schemas/V1Figure"},"answers":{"type":"integer","title":"Answers","default":0},"trend":{"anyOf":[{"$ref":"#/components/schemas/PromptTrend"},{"type":"null"}]}},"type":"object","required":["key","name","domain","is_you","heralded_score","mentioned","recommended","answers","trend"],"title":"V1PromptCompetitor"},"V1PromptDetail":{"properties":{"measurement_status":{"type":"string","enum":["new","measured"],"title":"Measurement Status","description":"New until a subscription weekly report scores it, then measured. Independent of tracking state.","default":"new"},"first_answers_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Answers At","description":"The first answered time, or the estimate while its prompt read is pending. Null when no estimate is available."},"first_score_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"First Score On","description":"The next weekly report's date for the market. Null before the brand has a weekly schedule."},"evidence":{"items":{"$ref":"#/components/schemas/V1TopicEvidence"},"type":"array","title":"Evidence","description":"The stored evidence behind the prompt: the buyer phrasing it was drafted from, then the questions members added to its topic, which feed the topic's next draft. Empty when nothing was recorded."},"synthesised":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Synthesised","description":"True when Heralded wrote the prompt with no buyer evidence behind it; null when it was written before drafts recorded their evidence, or by a member."},"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"product_cards":{"anyOf":[{"$ref":"#/components/schemas/ProductCardsCell"},{"type":"null"}],"description":"Product-card figures for ecommerce brands; null for other brands and Google search."},"markets_by_language":{"additionalProperties":{"type":"integer"},"type":"object","title":"Markets By Language","description":"Current markets in each language before filtering."},"markets_total":{"type":"integer","title":"Markets Total","description":"Current country and language markets.","default":0},"google_searches_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Google Searches Total","description":"Google searches before paging; null when details were not requested."},"figures":{"anyOf":[{"$ref":"#/components/schemas/V1SideFigures"},{"type":"null"}],"description":"The question's figures with their weekly trends and changes."},"insight":{"anyOf":[{"$ref":"#/components/schemas/ServedInsight"},{"type":"null"}],"description":"Where an engine's latest answer leaves you out: the piece that fits the question and the content work filed for it."},"languages":{"items":{"type":"string"},"type":"array","title":"Languages"},"master_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Master Version"},"wordings":{"items":{"$ref":"#/components/schemas/V1PromptWording"},"type":"array","title":"Wordings","description":"Compact reads return current market wordings, most answers first, five by default. With details and no wordings_limit, includes wording history."},"measurement":{"anyOf":[{"$ref":"#/components/schemas/KeywordMeasurement"},{"type":"null"}]},"id":{"type":"string","format":"uuid","title":"Id"},"text":{"type":"string","title":"Text"},"status":{"type":"string","enum":["active","paused","archived"],"title":"Status"},"status_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Status Since"},"tracked_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Tracked Since"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topic"},"topic_detail":{"anyOf":[{"$ref":"#/components/schemas/V1PromptTopic"},{"type":"null"}],"description":"The topic the prompt belongs to."},"intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent"},"period":{"$ref":"#/components/schemas/V1Period"},"score":{"$ref":"#/components/schemas/V1Figure"},"engines":{"items":{"$ref":"#/components/schemas/V1PromptLatestEngine"},"type":"array","title":"Engines"},"competitors":{"items":{"$ref":"#/components/schemas/V1PromptCompetitor"},"type":"array","title":"Competitors"},"competitors_total":{"type":"integer","title":"Competitors Total","description":"The prompt-filtered Competitors board's total."},"sources":{"items":{"$ref":"#/components/schemas/V1PromptSource"},"type":"array","title":"Sources"},"prompt_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Type"},"prompt_type_source":{"type":"string","enum":["member","heralded"],"title":"Prompt Type Source","default":"heralded"},"intent_source":{"type":"string","enum":["member","heralded"],"title":"Intent Source","default":"heralded"},"search_volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Volume"},"engine_vocabulary":{"items":{"$ref":"#/components/schemas/EngineVocabulary"},"type":"array","title":"Engine Vocabulary"},"tiles":{"items":{"$ref":"#/components/schemas/PromptTile"},"type":"array","title":"Tiles"},"answers":{"type":"integer","title":"Answers","default":0},"engine_cards":{"items":{"$ref":"#/components/schemas/PromptEngineCard"},"type":"array","title":"Engine Cards"},"third_report_due_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Third Report Due At"},"retention_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retention Days"},"actions":{"items":{"$ref":"#/components/schemas/V1PromptAction"},"type":"array","title":"Actions","description":"The first three live actions about this prompt, highest priority first."},"actions_total":{"type":"integer","title":"Actions Total","description":"Every live action about this subject, before the list is cut.","default":0},"next_step_action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Next Step Action Id","description":"The highest-priority live action that awaits a member and whose verb the reader may press; null when there is none."},"next_step":{"anyOf":[{"$ref":"#/components/schemas/V1PromptAction"},{"type":"null"}],"description":"The action `next_step_action_id` names, in the same shape as `actions`."},"answers_link":{"anyOf":[{"$ref":"#/components/schemas/AnswersLink"},{"type":"null"}]},"health":{"anyOf":[{"$ref":"#/components/schemas/PromptHealth"},{"type":"null"}],"description":"How often an active prompt's answers name any company, by week. Null until a week is measured."},"ai_searches":{"items":{"$ref":"#/components/schemas/V1AISearch"},"type":"array","title":"Ai Searches","description":"Observed engine searches tied to this prompt's dated answers. Leads for Google-rank checks, never buyer evidence or page-coverage questions. Empty when no retained answer exposes searches."},"google_searches":{"items":{"$ref":"#/components/schemas/V1PromptGoogleSearch"},"type":"array","title":"Google Searches","description":"The Google searches the engines ran for this prompt, one entry for each text and market, whatever the number of engines and days that ran it. Most searched first: monthly searches with unknown volumes last, then ranked before unranked by position, then A to Z. Paged with searches_limit and searches_offset when with_details is true. Empty when no retained answer exposes searches."},"sources_total":{"type":"integer","title":"Sources Total","description":"The distinct domains the prompt's answers in the period cite, of which `sources` lists the five cited most.","default":0}},"type":"object","required":["measurement_status","first_answers_at","first_score_on","evidence","synthesised","meta","product_cards","markets_by_language","markets_total","google_searches_total","figures","insight","languages","master_version","wordings","measurement","id","text","status","status_since","tracked_since","topic","topic_detail","intent","period","score","engines","competitors","competitors_total","sources","prompt_type","prompt_type_source","intent_source","search_volume","engine_vocabulary","tiles","answers","engine_cards","third_report_due_at","retention_days","actions","actions_total","next_step_action_id","next_step","answers_link","health","ai_searches","google_searches","sources_total"],"title":"V1PromptDetail"},"V1PromptEngine":{"properties":{"engine":{"type":"string","enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"title":"Engine"},"state":{"type":"string","enum":["leading","recommended","mentioned","weak","absent","unmeasured"],"title":"State"},"answer_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Answer Id"},"reading":{"type":"boolean","title":"Reading","default":false}},"type":"object","required":["engine","state","answer_id","reading"],"title":"V1PromptEngine"},"V1PromptGoogleSearch":{"properties":{"text":{"type":"string","title":"Text","description":"The search as the newest answer that ran it worded it. The same search in another market is another entry."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"The market's country, ISO 3166-1 alpha-2 in upper case. Null for Global and for a pooled Europe answer with no asked country."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"The market's language code. Null where the market was not resolved."},"engines":{"items":{"type":"string"},"type":"array","title":"Engines","description":"Every engine that ran this search, in the engine vocabulary's order."},"answers":{"type":"integer","title":"Answers","description":"Number of distinct prompt answers in the period that ran this search."},"searches_mo":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Searches Mo","description":"Monthly Google searches for the text in the market, from the latest volume Heralded priced. Null when none is priced or the vendor had no figure; 0 is a confirmed zero."},"volume_state":{"type":"string","enum":["measured","zero","no_data","pending"],"title":"Volume State","description":"Whether monthly search volume was measured, confirmed zero, returned without a number, or has not been priced yet."},"google_rank":{"$ref":"#/components/schemas/V1GoogleRank","description":"Your Google rank for this search in this market, as `ai_searches` serves it for the same search."},"keyword_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Keyword Id","description":"The prompt's topic keyword with this text in this market, tracked or archived. Null when none."},"last_searched_at":{"type":"string","format":"date-time","title":"Last Searched At","description":"When the newest answer that ran it completed."}},"type":"object","required":["text","country","language","engines","answers","searches_mo","volume_state","google_rank","keyword_id","last_searched_at"],"title":"V1PromptGoogleSearch"},"V1PromptLatestEngine":{"properties":{"engine":{"type":"string","enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"],"title":"Engine"},"state":{"type":"string","enum":["leading","recommended","mentioned","weak","absent","unmeasured"],"title":"State"},"answer_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Answer Id"},"reading":{"type":"boolean","title":"Reading","default":false},"display_name":{"type":"string","title":"Display Name"},"read_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Read At"},"states":{"$ref":"#/components/schemas/AnswerReadStates"}},"type":"object","required":["engine","state","answer_id","reading","display_name","read_at","states"],"title":"V1PromptLatestEngine"},"V1PromptSource":{"properties":{"source_type":{"anyOf":[{"type":"string","enum":["industry_authority","review","regulatory","media","educational","community","consulting","social","vendor","directory","unclassified"]},{"type":"string","const":"corporate"}],"title":"Source Type","description":"The site's type, using the Sources vocabulary."},"owner":{"type":"string","enum":["third_party","competitor","yours"],"title":"Owner","description":"Whether the site is yours, a competitor's or third-party."},"domain":{"type":"string","title":"Domain"},"citations":{"type":"integer","title":"Citations"},"group":{"type":"string","enum":["own","rival","review","editorial","community","vendor","other"],"title":"Group"},"relation":{"anyOf":[{"type":"string","enum":["yours","names_you","doesnt_name_you"]},{"type":"null"}],"title":"Relation"}},"type":"object","required":["source_type","owner","domain","citations","group","relation"],"title":"V1PromptSource"},"V1PromptTopic":{"properties":{"market":{"type":"string","title":"Market","description":"The topic's market: country ISO code, europe or global.","default":"global"},"audience":{"type":"string","title":"Audience","description":"The topic's audience name.","default":"All buyers"},"audience_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Audience Id","description":"Audience UUID; null for All buyers."},"tracked_topic_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Tracked Topic Id","description":"Tracked-topic UUID."},"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"need":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Need"},"scores":{"anyOf":[{"$ref":"#/components/schemas/TopicScores"},{"type":"null"}],"description":"The topic's Heralded Score on each side, as topics states it."}},"type":"object","required":["market","audience","audience_id","tracked_topic_id","id","name","need","scores"],"title":"V1PromptTopic"},"V1PromptWording":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"language":{"type":"string","title":"Language"},"version":{"type":"integer","title":"Version"},"text":{"type":"string","title":"Text"},"answers":{"type":"integer","title":"Answers"},"mentioned":{"type":"integer","title":"Mentioned"},"mentioned_pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentioned Pct","description":"Mentioned over answers in whole points, rounded half up. Null when the wording has no answers.","readOnly":true}},"type":"object","required":["id","country","language","version","text","answers","mentioned","mentioned_pct"],"title":"V1PromptWording"},"V1Prompts":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"measurement":{"anyOf":[{"$ref":"#/components/schemas/KeywordMeasurement"},{"type":"null"}]},"prompts":{"items":{"$ref":"#/components/schemas/V1Prompt"},"type":"array","title":"Prompts"},"engine_vocabulary":{"items":{"$ref":"#/components/schemas/EngineVocabulary"},"type":"array","title":"Engine Vocabulary"},"period":{"anyOf":[{"$ref":"#/components/schemas/V1Period"},{"type":"null"}]},"filters":{"$ref":"#/components/schemas/PromptFilters"},"tracked_total":{"type":"integer","title":"Tracked Total","description":"Tracked prompts under market, audience, type, intent, topic and prompt filters, before text and brand-presence filters.","default":0},"active_total":{"type":"integer","title":"Active Total","description":"Active prompts using the brand prompt allowance, before list filters.","default":0},"archived_total":{"type":"integer","title":"Archived Total","description":"Archived prompts in the brand, before list filters.","default":0},"has_more":{"type":"boolean","title":"Has More","default":false},"sort":{"type":"string","enum":["volume","change","presence","name","prompt","score","trend"],"title":"Sort","default":"volume"},"prompt_text_max_len":{"type":"integer","title":"Prompt Text Max Len","default":200}},"type":"object","required":["meta","next_cursor","total","limit","offset","measurement","prompts","engine_vocabulary","period","filters","tracked_total","active_total","archived_total","has_more","sort","prompt_text_max_len"],"title":"V1Prompts","examples":[{"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"total":1,"limit":20,"offset":0,"measurement":null,"prompts":[{"product_cards":null,"measurement_status":"new","first_answers_at":null,"first_score_on":null,"evidence":[],"synthesised":null,"insight":null,"languages":[],"master_version":null,"wordings":[],"measurement":null,"id":"0b8e5f7a-2c4d-4e6f-8a1b-3c5d7e9f1a2b","text":"best crm for agencies","status":"active","topic":"CRM","market":"global","audience":"All buyers","audience_id":null,"tracked_topic_id":null,"intent":"comparison","engines":[{"engine":"openai","state":"recommended","answer_id":"5d2e8c1f-7a3b-4c6d-9e0f-1a2b3c4d5e6f","reading":false}],"status_since":null,"prompt_type":null,"search_volume":null,"change":null,"score":null,"trend":null,"marks":[],"cells":[],"low_signal":false,"ai_searches":[]}],"engine_vocabulary":[],"period":null,"filters":{"types":[],"intents":[],"topics":[]},"tracked_total":0,"active_total":0,"archived_total":0,"has_more":false,"sort":"volume","prompt_text_max_len":200}]},"V1RankPoint":{"properties":{"at":{"type":"string","format":"date-time","title":"At","description":"The report's time, equal to `figures.mentioned.trend[].at`."},"state":{"type":"string","title":"State","description":"ranked means one of your pages is in the report's newest fetched check of the keyword, at `position`. not_in_top_10 means the check was fetched and none of your pages is in its ten results. unchecked means the report holds no fetched check of the keyword. New states may be added; handle unknown values gracefully.","x-extensible-enum":["ranked","not_in_top_10","unchecked"]},"position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Position","description":"Your best (lowest) position, 1 to 10, in that check; null unless ranked."},"break":{"anyOf":[{"$ref":"#/components/schemas/TrendBreak"},{"type":"null"}],"description":"The break the matching `figures.mentioned.trend` point carries: a new baseline at this date."},"competitors_ahead":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Competitors Ahead","description":"Competitor results above your best rank, or all ten when you are outside them."}},"type":"object","required":["at","state","position","break","competitors_ahead"],"title":"V1RankPoint","description":"Your best Google position for a keyword at one weekly report."},"V1ReadRequest":{"properties":{"kind":{"type":"string","enum":["question","description","logo","link","test_account","billing_details","article","rates","other"],"title":"Kind","description":"What they ask the brand for."},"text":{"type":"string","title":"Text","description":"The request in one short line."},"deadline":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Deadline","description":"When they need it by, if they said."}},"type":"object","required":["kind","text","deadline"],"title":"V1ReadRequest"},"V1Readiness":{"properties":{"pages_checked":{"type":"integer","title":"Pages Checked"},"pages_readable":{"type":"integer","title":"Pages Readable"},"pages_blocked":{"type":"integer","title":"Pages Blocked"},"pages_unmeasured":{"type":"integer","title":"Pages Unmeasured"}},"type":"object","required":["pages_checked","pages_readable","pages_blocked","pages_unmeasured"],"title":"V1Readiness","description":"The pages the readiness checks cover: every audited page and the homepage."},"V1Region":{"properties":{"x":{"type":"number","title":"X"},"y":{"type":"number","title":"Y"},"w":{"type":"number","title":"W"},"h":{"type":"number","title":"H"}},"type":"object","required":["x","y","w","h"],"title":"V1Region"},"V1Regions":{"properties":{"headline":{"anyOf":[{"$ref":"#/components/schemas/V1Region"},{"type":"null"}]},"call_to_action":{"anyOf":[{"$ref":"#/components/schemas/V1Region"},{"type":"null"}]}},"type":"object","required":["headline","call_to_action"],"title":"V1Regions"},"V1Reputation":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headline","description":"Written statement or templated sentence over served figures; null when Understood has no measured value."},"facts_summary":{"$ref":"#/components/schemas/FactSummary","description":"Mostly-right and measured fact counts, plus fact keys with insufficient addressing answers."},"domain":{"type":"string","title":"Domain"},"period":{"$ref":"#/components/schemas/V1Period"},"filters":{"$ref":"#/components/schemas/FigureFilters"},"written":{"$ref":"#/components/schemas/V1PerceptionWrittenPieces"},"understood":{"$ref":"#/components/schemas/V1Figure","description":"0.63 × the AI part + 0.37 × the web part; the AI part alone under ten documents or a filter."},"praised":{"$ref":"#/components/schemas/V1Figure"},"parts":{"$ref":"#/components/schemas/V1ReputationParts"},"facts":{"items":{"$ref":"#/components/schemas/V1ReputationFact"},"type":"array","title":"Facts"},"opinions":{"items":{"$ref":"#/components/schemas/V1ReputationOpinion"},"type":"array","title":"Opinions","description":"What voices think of the brand, held in the period's reports: negative first, then the most held. A claim becomes an opinion once three distinct holders state it within 28 days. Filters do not narrow them."},"negative_prompts":{"items":{"$ref":"#/components/schemas/V1PerceptionNegativePrompt"},"type":"array","title":"Negative Prompts"},"negative_sources":{"items":{"$ref":"#/components/schemas/V1PerceptionNegativeSource"},"type":"array","title":"Negative Sources"},"negative_prompts_total":{"type":"integer","title":"Negative Prompts Total","description":"All prompts with negative evidence before paging."},"negative_sources_total":{"type":"integer","title":"Negative Sources Total","description":"All sources with negative evidence before paging."},"best_quotes":{"items":{"$ref":"#/components/schemas/V1PerceptionBestQuote"},"type":"array","title":"Best Quotes"}},"type":"object","required":["meta","headline","facts_summary","domain","period","filters","written","understood","praised","parts","facts","opinions","negative_prompts","negative_sources","negative_prompts_total","negative_sources_total","best_quotes"],"title":"V1Reputation"},"V1ReputationClaim":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"period":{"$ref":"#/components/schemas/V1Period"},"filters":{"$ref":"#/components/schemas/FigureFilters"},"claim":{"$ref":"#/components/schemas/V1ReputationFact"},"added_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Added At"},"quotes":{"items":{"$ref":"#/components/schemas/V1PerceptionQuotedLine"},"type":"array","title":"Quotes"},"prompts":{"items":{"$ref":"#/components/schemas/V1PerceptionClaimPrompt"},"type":"array","title":"Prompts"},"engines":{"items":{"$ref":"#/components/schemas/V1PerceptionClaimEngine"},"type":"array","title":"Engines"},"pages":{"items":{"$ref":"#/components/schemas/V1PerceptionContradictingPage"},"type":"array","title":"Pages"},"documents":{"items":{"$ref":"#/components/schemas/V1ReputationDocument"},"type":"array","title":"Documents","description":"The pages behind `claim.elsewhere`, contradicting first."},"prompts_total":{"type":"integer","title":"Prompts Total","description":"All prompts matching this selection before paging."},"pages_total":{"type":"integer","title":"Pages Total","description":"All pages under the selected filters before paging."},"answers_link":{"$ref":"#/components/schemas/AnswersLink"}},"type":"object","required":["meta","period","filters","claim","added_at","quotes","prompts","engines","pages","documents","prompts_total","pages_total","answers_link"],"title":"V1ReputationClaim"},"V1ReputationDocument":{"properties":{"language":{"type":"string","title":"Language","default":"unknown"},"url":{"type":"string","title":"Url"},"domain":{"type":"string","title":"Domain"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"verdict":{"type":"string","enum":["agrees","contradicts"],"title":"Verdict"},"passage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Passage"}},"type":"object","required":["language","url","domain","title","verdict","passage"],"title":"V1ReputationDocument"},"V1ReputationElsewhere":{"properties":{"agrees":{"type":"integer","title":"Agrees"},"contradicts":{"type":"integer","title":"Contradicts"}},"type":"object","required":["agrees","contradicts"],"title":"V1ReputationElsewhere"},"V1ReputationFact":{"properties":{"definition":{"anyOf":[{"$ref":"#/components/schemas/BrandFact"},{"type":"null"}],"description":"The current member-added fact, including kind, check, question, definition_version and author. Null for profile claims. Its version can be newer than the evidence behind wording and ai."},"insight":{"anyOf":[{"$ref":"#/components/schemas/ServedInsight"},{"type":"null"}],"description":"An actionable contradicting-page insight, preferring existing work. Null when no page offers work."},"key":{"type":"string","title":"Key"},"kind":{"type":"string","enum":["category","audience","offer","difference","fact"],"title":"Kind"},"wording":{"type":"string","title":"Wording"},"quote":{"anyOf":[{"$ref":"#/components/schemas/V1PerceptionQuotedLine"},{"type":"null"}]},"ai":{"$ref":"#/components/schemas/V1PerceptionVerdicts","description":"The AI answers read against it."},"origins":{"anyOf":[{"$ref":"#/components/schemas/V1FactOrigins"},{"type":"null"}],"description":"A fact's verdict counts split by origin: its own question (`probe`) or tracked prompts that name the brand (`prompt`). Null for a profile claim."},"definition_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Definition Version","description":"The fact definition version the counts were read against; null for a profile claim or for readings from before definitions were versioned."},"current_version_pending":{"type":"boolean","title":"Current Version Pending","description":"The fact was edited to a new definition no report has read yet; the counts are of `definition_version`.","default":false},"elsewhere":{"$ref":"#/components/schemas/V1ReputationElsewhere","description":"The pages AI cited and Google ranked that name the brand and agree or contradict it. Zero under a filter, which a page has no value for."},"trend":{"$ref":"#/components/schemas/V1PerceptionClaimTrend"},"state":{"anyOf":[{"$ref":"#/components/schemas/V1PerceptionClaimState"},{"type":"null"}]},"parts":{"items":{"$ref":"#/components/schemas/V1ReputationStatementPart"},"type":"array","title":"Parts","description":"A profile statement's parts, where the latest report measured Understood part by part; empty for a fact or a statement measured whole."}},"type":"object","required":["definition","insight","key","kind","wording","quote","ai","origins","definition_version","current_version_pending","elsewhere","trend","state","parts"],"title":"V1ReputationFact"},"V1ReputationOpinion":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"label":{"type":"string","title":"Label"},"tone":{"type":"string","enum":["positive","negative"],"title":"Tone"},"held_by":{"type":"integer","title":"Held By","description":"Distinct holders in the period: each AI answer and each document once."},"kinds":{"additionalProperties":{"type":"integer"},"type":"object","title":"Kinds","description":"Holders by kind: `ai_answer`, then the kind of each document (`thread`, `post`, `article`, `video`, `podcast`, `review`, `page`)."},"engines":{"items":{"type":"string"},"type":"array","title":"Engines","description":"The engines with an answer that holds it."},"change":{"type":"integer","title":"Change","description":"Distinct holders in the selected reports less those of their baseline."},"change_detail":{"anyOf":[{"$ref":"#/components/schemas/V1Change"},{"type":"null"}],"description":"The selected period's holder change, baseline and figure test's verdict; null without a comparable baseline."},"action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Action Id","description":"The action filed to answer it, if any."},"insight":{"anyOf":[{"$ref":"#/components/schemas/ServedInsight"},{"type":"null"}],"description":"The work that fits it, a piece answering a negative opinion, and the work filed from it."}},"type":"object","required":["id","label","tone","held_by","kinds","engines","change","change_detail","action_id","insight"],"title":"V1ReputationOpinion"},"V1ReputationOpinionHolder":{"properties":{"asked_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asked Language"},"language":{"type":"string","title":"Language","default":"unknown"},"kind":{"type":"string","title":"Kind","description":"`ai_answer`, or the document's kind."},"engine":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Engine","description":"The engine of an AI answer."},"prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt","description":"The prompt an AI answer was asked under."},"prompt_uid":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Prompt Uid","description":"The tracked prompt an AI answer was asked under."},"answer_read_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Answer Read Id","description":"The AI answer itself, at `/v1/brands/{brand_id}/answers/{answer_id}`."},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published At"},"held_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Held At","description":"When the report that froze it completed."},"passage":{"type":"string","title":"Passage","description":"The words that state it."}},"type":"object","required":["asked_language","language","kind","engine","prompt","prompt_uid","answer_read_id","platform","url","domain","title","published_at","held_at","passage"],"title":"V1ReputationOpinionHolder"},"V1ReputationOpinionPane":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"period":{"$ref":"#/components/schemas/V1Period"},"opinion":{"$ref":"#/components/schemas/V1ReputationOpinion"},"holders":{"items":{"$ref":"#/components/schemas/V1ReputationOpinionHolder"},"type":"array","title":"Holders","description":"Newest first, at most `list_limit`."},"holders_total":{"type":"integer","title":"Holders Total","description":"Distinct answers and pages holding this opinion before paging."}},"type":"object","required":["meta","period","opinion","holders","holders_total"],"title":"V1ReputationOpinionPane"},"V1ReputationPart":{"properties":{"understood":{"$ref":"#/components/schemas/V1Figure"},"praised":{"$ref":"#/components/schemas/V1Figure"}},"type":"object","required":["understood","praised"],"title":"V1ReputationPart"},"V1ReputationParts":{"properties":{"ai":{"$ref":"#/components/schemas/V1ReputationPart","description":"The AI answers naming the brand."},"web":{"$ref":"#/components/schemas/V1ReputationPart","description":"The pages AI cited and Google ranked that name the brand, one reading per document. Not measured under ten documents, where `understood` and `praised` are the AI part alone."}},"type":"object","required":["ai","web"],"title":"V1ReputationParts"},"V1ReputationStatementPart":{"properties":{"key":{"type":"string","title":"Key","description":"The part's stable key, kept across rewordings of its meaning."},"wording":{"type":"string","title":"Wording","description":"The part as the latest report measured it."},"quote":{"anyOf":[{"$ref":"#/components/schemas/V1PerceptionQuotedLine"},{"type":"null"}],"description":"An answer's words on the part, contradicting first; null where no answer quotes it."},"ai":{"$ref":"#/components/schemas/V1PerceptionVerdicts","description":"The AI answers naming the brand read against it; `doesnt_say` counts those that never mention it."},"elsewhere":{"$ref":"#/components/schemas/V1ReputationElsewhere","description":"The pages AI cited and Google ranked that name the brand and agree or contradict it. Zero under a filter, which a page has no value for."},"trend":{"$ref":"#/components/schemas/V1PerceptionClaimTrend","description":"The change in the share of answers contradicting it; no change is called across a change in how Understood was measured."}},"type":"object","required":["key","wording","quote","ai","elsewhere","trend"],"title":"V1ReputationStatementPart","description":"One part of a profile statement, as the latest report measured it."},"V1Results":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total","description":"All delivered actions before paging."},"limit":{"type":"integer","title":"Limit","description":"The requested maximum rows per page."},"offset":{"type":"integer","title":"Offset","description":"Rows skipped before this page."},"rows":{"items":{"$ref":"#/components/schemas/ResultRow"},"type":"array","title":"Rows","description":"One page of delivered actions and their results."},"counts":{"additionalProperties":{"type":"integer"},"propertyNames":{"enum":["Delivered","Cited","Paying off"]},"type":"object","title":"Counts","description":"All delivered actions by result label, independent of order and page."}},"type":"object","required":["meta","next_cursor","total","limit","offset","rows","counts"],"title":"V1Results","examples":[{"rows":[],"counts":{"Paying off":0,"Cited":0,"Delivered":0},"total":0,"limit":20,"offset":0,"next_cursor":null,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}}}]},"V1Revenue":{"properties":{"revenue":{"type":"number","title":"Revenue","description":"Revenue in the read's currency, a minimum."},"orders":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Orders","description":"Purchases; null for a product, counted in units."},"key_events":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Key Events","description":"Key events; null for a product."},"visits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Visits","description":"Google Analytics sessions; null where it gives none for the cut."},"items":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Items","description":"Units bought; only for a product."},"average_order":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Order","description":"Revenue per order; null without orders."},"conversion":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Conversion","description":"Orders per visit in [0, 1]; null without a visit count."}},"type":"object","required":["revenue","orders","key_events","visits","items","average_order","conversion"],"title":"V1Revenue"},"V1RevenueFromAi":{"properties":{"currency":{"type":"string","title":"Currency","description":"The Google Analytics property's currency."},"window_start":{"type":"string","format":"date","title":"Window Start","description":"The first day the read covers."},"window_end":{"type":"string","format":"date","title":"Window End","description":"The last day the read covers."},"minimum":{"type":"boolean","const":true,"title":"Minimum","description":"Revenue from AI is a minimum: visits from assistant apps without a referrer, AI Overviews and AI Mode cannot be told apart from other traffic.","default":true},"total":{"$ref":"#/components/schemas/V1Revenue","description":"Every AI assistant together."},"share_of_site":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Share Of Site","description":"AI assistants' revenue as a share of the whole site's in the window."},"assistants":{"items":{"$ref":"#/components/schemas/V1AssistantRevenue"},"type":"array","title":"Assistants","description":"By assistant, most revenue first."},"by_product":{"type":"boolean","title":"By Product","description":"Whether revenue could be split by product for this property."},"pages":{"items":{"$ref":"#/components/schemas/V1PageRevenue"},"type":"array","title":"Pages","description":"One page of the landing pages, most revenue first, with the topics and questions whose answers cite each."},"pages_total":{"type":"integer","title":"Pages Total","description":"Landing pages with revenue from AI before paging."},"pages_limit":{"type":"integer","title":"Pages Limit","description":"Landing pages per page."},"pages_offset":{"type":"integer","title":"Pages Offset","description":"Landing pages skipped."},"trend":{"items":{"$ref":"#/components/schemas/V1RevenuePoint"},"type":"array","title":"Trend","description":"One point per weekly read of the property in the period, oldest first."}},"type":"object","required":["currency","window_start","window_end","minimum","total","share_of_site","assistants","by_product","pages","pages_total","pages_limit","pages_offset","trend"],"title":"V1RevenueFromAi"},"V1RevenuePoint":{"properties":{"scan_id":{"type":"string","format":"uuid","title":"Scan Id","description":"The weekly report that read it."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When the report completed."},"window_start":{"type":"string","format":"date","title":"Window Start","description":"The first day the read covers."},"window_end":{"type":"string","format":"date","title":"Window End","description":"The last day the read covers."},"currency":{"type":"string","title":"Currency","description":"The property's currency for this read."},"revenue":{"type":"number","title":"Revenue","description":"Every AI assistant together, a minimum."},"orders":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Orders","description":"Purchases."},"visits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Visits","description":"Google Analytics sessions."}},"type":"object","required":["scan_id","completed_at","window_start","window_end","currency","revenue","orders","visits"],"title":"V1RevenuePoint"},"V1RevenueQuestion":{"properties":{"id":{"type":"string","title":"Id","description":"The question's prompt id, or its query id."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text","description":"The question's current wording."},"topic_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Topic Id","description":"The topic it belongs to, where it has one."},"answers":{"type":"integer","title":"Answers","description":"Answers to it in the period that cite the page."}},"type":"object","required":["id","text","topic_id","answers"],"title":"V1RevenueQuestion"},"V1RevenueTopic":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The topic's id, which the list's topic filter takes."},"name":{"type":"string","title":"Name","description":"The topic's name."},"answers":{"type":"integer","title":"Answers","description":"Answers on the topic in the period that cite the page."}},"type":"object","required":["id","name","answers"],"title":"V1RevenueTopic"},"V1Review":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"id":{"type":"string","format":"uuid","title":"Id"},"platform":{"type":"string","title":"Platform"},"stars":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Stars"},"title":{"type":"string","title":"Title"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Excerpt"},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published At"},"opinions":{"items":{"type":"string"},"type":"array","title":"Opinions"},"replied":{"type":"boolean","title":"Replied"},"action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Action Id"}},"type":"object","required":["meta","id","platform","stars","title","excerpt","published_at","opinions","replied","action_id"],"title":"V1Review"},"V1ReviewPlatform":{"properties":{"platform":{"type":"string","title":"Platform"},"name":{"type":"string","title":"Name"},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating"},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Count"},"last_90_days":{"type":"integer","title":"Last 90 Days"},"ai_citation_share":{"type":"number","title":"Ai Citation Share","description":"Share of your counted AI answers in the period that cite this platform, 0 to 1."},"rivals":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Rivals"},"connected":{"type":"boolean","title":"Connected"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"}},"type":"object","required":["platform","name","rating","count","last_90_days","ai_citation_share","rivals","connected","source"],"title":"V1ReviewPlatform"},"V1Reviews":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"features":{"additionalProperties":{"type":"boolean"},"type":"object","title":"Features"},"platforms":{"items":{"$ref":"#/components/schemas/V1ReviewPlatform"},"type":"array","title":"Platforms"},"work":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Work"},"reviews":{"items":{"$ref":"#/components/schemas/V1Review"},"type":"array","title":"Reviews"}},"type":"object","required":["meta","next_cursor","total","limit","offset","features","platforms","work","reviews"],"title":"V1Reviews","examples":[{"features":{},"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"platforms":[],"reviews":[],"total":0,"work":[]}]},"V1RivalGaps":{"properties":{"count":{"type":"integer","title":"Count","description":"Prompts a tracked rival wins and the brand does not."},"prompts":{"type":"integer","title":"Prompts","description":"Every prompt read."},"top":{"items":{"type":"string"},"type":"array","title":"Top","description":"The highest-demand of those prompts."}},"type":"object","required":["count","prompts","top"],"title":"V1RivalGaps"},"V1RivalPageRead":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"rival":{"$ref":"#/components/schemas/RivalPagePane","description":"The selected competitor page and its bounded citing questions and URL-specific work."}},"type":"object","required":["meta","rival"],"title":"V1RivalPageRead"},"V1RivalSources":{"properties":{"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Count","description":"Third-party sources citing rivals and never the brand; null while a scan's citations are unavailable."},"top":{"items":{"type":"string"},"type":"array","title":"Top"},"unavailable_scans":{"type":"integer","title":"Unavailable Scans"}},"type":"object","required":["count","top","unavailable_scans"],"title":"V1RivalSources"},"V1RunRequest":{"properties":{"state":{"type":"string","enum":["requested","stopped","needs_action"],"title":"State","description":"`requested`: the run starts once the profile is drafted. `stopped`: an edit or Stop cancelled it; Run again to start it. `needs_action`: it could not start, for `reason`."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why a `needs_action` run did not start, as an error code such as `no_credits`; null otherwise."}},"type":"object","required":["state","reason"],"title":"V1RunRequest","description":"Run pressed on a Snapshot that has not started."},"V1Scan":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"id":{"type":"string","format":"uuid","title":"Id","description":"The scan's id."},"kind":{"type":"string","enum":["weekly","daily","snapshot","audit"],"title":"Kind","description":"`weekly`, `daily`, `snapshot` (a one-time Snapshot or a brand's first) or `audit`."},"state":{"type":"string","enum":["preparing","running","completed","failed","expired"],"title":"State","description":"`preparing` while the profile drafts or waits for Run, `running`, `completed`, `failed`, or `expired`: a Snapshot whose profile waited 24 hours without a run."},"partial":{"type":"boolean","title":"Partial","description":"A Snapshot delivered before every answer came back, still filling in."},"brand_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Brand Id","description":"Null for a Snapshot no brand holds."},"domain":{"type":"string","title":"Domain","description":"The site the scan measured."},"sells_to":{"type":"string","enum":["businesses","consumers"],"title":"Sells To","description":"Who the scan measured the brand as selling to: `businesses` or `consumers`. Fixed for the scan once it runs."},"ecommerce":{"type":"boolean","title":"Ecommerce","description":"Whether the scan measured the brand as ecommerce, which reads product cards and Google Shopping. Fixed for the scan once it runs."},"started_at":{"type":"string","format":"date-time","title":"Started At","description":"When the scan was started."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When it completed, failed or expired; null until then."},"questions_asked":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Questions Asked","description":"How many questions the scan asks AI engines. A Snapshot asks 20, or 12 to 19 when fewer of its drafted questions passed review. Null before its questions are fixed and on an Audit."},"profile":{"anyOf":[{"$ref":"#/components/schemas/V1SnapshotProfile"},{"type":"null"}],"description":"A preparing Snapshot's profile, to confirm or edit before Run; null while it drafts and once the Snapshot runs."},"run_request":{"anyOf":[{"$ref":"#/components/schemas/V1RunRequest"},{"type":"null"}],"description":"Run pressed before the Snapshot started; null otherwise."},"payer":{"anyOf":[{"$ref":"#/components/schemas/V1SnapshotPayer"},{"type":"null"}],"description":"Who pays for a Snapshot: recorded on Run, charged when it starts. A run that needs action keeps the payer it waits on. Null before Run, after a stop and on other scans."},"share_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Share Id","description":"The report link id once delivered; null on a daily scan and before delivery. Quick shares use /v1/shared/audits/{share_id}; Base and Full remain owner-only."},"report_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Url","description":"A delivered Snapshot's or weekly scan's report page, to give the member; null on an Audit, a daily scan and before delivery."},"progress":{"anyOf":[{"$ref":"#/components/schemas/V1ScanProgress"},{"type":"null"}],"description":"Null on an Audit and once the scan completed or failed."},"audit_progress":{"anyOf":[{"$ref":"#/components/schemas/AuditProgress"},{"type":"null"}],"description":"An Audit's live page and screenshot counts; null on other scans."},"failure_reason":{"anyOf":[{"type":"string","x-extensible-enum":["stuck_no_progress","brief_abandoned","insufficient_engine_signal","cost_cap_exceeded","report_inputs_missing","service_unavailable","other"]},{"type":"null"}],"title":"Failure Reason","description":"Why the scan failed, one of `stuck_no_progress`, `brief_abandoned`, `insufficient_engine_signal`, `cost_cap_exceeded`, `report_inputs_missing`, `service_unavailable` or `other`; null unless the scan failed. New values may be added."},"issued":{"anyOf":[{"$ref":"#/components/schemas/V1ScanFacts"},{"type":"null"}],"description":"What the scan issued once complete; null while it runs, while it is partial, on a daily scan and on an Audit."}},"type":"object","required":["meta","id","kind","state","partial","brand_id","domain","sells_to","ecommerce","started_at","completed_at","questions_asked","profile","run_request","payer","share_id","report_url","progress","audit_progress","failure_reason","issued"],"title":"V1Scan"},"V1ScanAudit":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"id":{"type":"string","format":"uuid","title":"Id","description":"The scan's id."},"share_id":{"type":"string","format":"uuid","title":"Share Id","description":"The scan's report link id, as in /r/{share_id}."},"domain":{"type":"string","title":"Domain","description":"The host the read crawled."},"brand_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Name"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"},"content_pass":{"type":"string","enum":["running","failed","done"],"title":"Content Pass","description":"Whether the page and topic read is still running, failed or done. The fields below it fill in once it is done."},"readiness":{"anyOf":[{"$ref":"#/components/schemas/V1Readiness"},{"type":"null"}],"description":"AI engines' access to the pages this scan checked; null where it checked none."},"moves":{"items":{"$ref":"#/components/schemas/RenderedMove"},"type":"array","title":"Moves","description":"The work Heralded's plays would file for this scan, best first: at most 5, at most 2 of one play, none below a medium expected gain. A Snapshot's are its report's priority actions."},"pillars":{"items":{"$ref":"#/components/schemas/ContentReadPillar"},"type":"array","title":"Pillars","description":"How many pages pass each page check."},"pages":{"items":{"$ref":"#/components/schemas/ContentReadPage"},"type":"array","title":"Pages","description":"Every audited page, best fix first: value times gap, then value."},"missing_topics":{"items":{"$ref":"#/components/schemas/ContentReadMissingTopic"},"type":"array","title":"Missing Topics","description":"Topics buyers ask about that the site has no page for. A Snapshot names its top ones; an Audit names every one."},"missing_topics_total":{"type":"integer","title":"Missing Topics Total","description":"Every topic the read found missing."},"snapshot_share_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Snapshot Share Id","description":"The report link id of the caller's own delivered Snapshot of this site, when there is one."},"site_blockers":{"anyOf":[{"$ref":"#/components/schemas/SiteBlockers"},{"type":"null"}],"description":"What stops AI engines reading the pages this scan checked, with the fix for each; null where it checked none."},"site_checks":{"anyOf":[{"$ref":"#/components/schemas/SiteChecks"},{"type":"null"}],"description":"The site and homepage checks this scan measured, each met or not against its target; null where it stored none."},"website":{"anyOf":[{"$ref":"#/components/schemas/V1Website"},{"type":"null"}],"description":"An Audit's Website score, findings and coverage from its own run; null on a Snapshot."},"brief":{"anyOf":[{"$ref":"#/components/schemas/V1AuditBrief"},{"type":"null"}],"description":"The brief the scan confirmed, each buyer question with its matched page; null where it has none."},"look":{"anyOf":[{"$ref":"#/components/schemas/Look"},{"type":"null"}],"description":"The brand's logo, colours, fonts, buttons and corner radius as the homepage showed them; null where none was read."}},"type":"object","required":["meta","id","share_id","domain","brand_name","completed_at","content_pass","readiness","moves","pillars","pages","missing_topics","missing_topics_total","snapshot_share_id","site_blockers","site_checks","website","brief","look"],"title":"V1ScanAudit","description":"The Content read of a Snapshot or Audit the caller ran: every audited\npage ranked best fix first, the page checks, the site's readability and the\ntopics it has no page for. `readiness` is Audit's, and the check rows share\nAudit's field names. This read has no crawl table, so its pages are the\ngraded ones."},"V1ScanFacts":{"properties":{"heralded_score":{"anyOf":[{"$ref":"#/components/schemas/V1IssuedScore"},{"type":"null"}],"description":"The Heralded Score this Snapshot issued."},"mentioned":{"anyOf":[{"$ref":"#/components/schemas/V1IssuedRate"},{"type":"null"}],"description":"Mentioned, ranked among this Snapshot's rivals."},"recommended":{"anyOf":[{"$ref":"#/components/schemas/V1IssuedRate"},{"type":"null"}],"description":"Recommended, ranked among this Snapshot's rivals."},"missing_question":{"anyOf":[{"$ref":"#/components/schemas/RivalQuestion"},{"type":"null"}],"description":"The unbranded question the strongest scored competitor was named for most often while you went unnamed. Null when it won none. Tied competitors follow name order; tied questions follow the order asked."},"readiness":{"anyOf":[{"$ref":"#/components/schemas/V1Readiness"},{"type":"null"}],"description":"AI engines' access to the pages this scan checked; null where it checked none."}},"type":"object","required":["heralded_score","mentioned","recommended","missing_question","readiness"],"title":"V1ScanFacts"},"V1ScanProgress":{"properties":{"phase":{"type":"string","title":"Phase","description":"The step the scan is on, such as engines or scoring."},"pct":{"type":"integer","title":"Pct"},"answers_read":{"type":"integer","title":"Answers Read","description":"Answers that came back so far, failed ones included."},"answers_total":{"type":"integer","title":"Answers Total","description":"Answers planned for this scan."},"pages_checked":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages Checked","description":"Cited pages read so far; null before then."},"pages_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages Total","description":"Cited page URLs scheduled for verification in this scan; null before then."}},"type":"object","required":["phase","pct","answers_read","answers_total","pages_checked","pages_total"],"title":"V1ScanProgress"},"V1ScanRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"kind":{"type":"string","enum":["weekly","daily","snapshot"],"title":"Kind"},"state":{"type":"string","enum":["preparing","running","completed","failed","expired"],"title":"State","description":"`preparing` while the profile drafts or waits for Run, `running`, `completed` or `failed`."},"domain":{"type":"string","title":"Domain"},"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market","description":"The market label the Snapshot report shows; null for weekly and daily scans."},"started_at":{"type":"string","format":"date-time","title":"Started At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"},"share_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Share Id","description":"The share link id of a delivered weekly scan or Snapshot, for /v1/shared/scans/{share_id}; null on a daily scan and before delivery."},"report_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Url","description":"The delivered report's page, to give the member; null when share_id is."},"progress_pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Progress Pct","description":"How far a scan that is preparing or running has come; null once it completed or failed."},"failure_reason":{"anyOf":[{"type":"string","x-extensible-enum":["stuck_no_progress","brief_abandoned","insufficient_engine_signal","cost_cap_exceeded","report_inputs_missing","service_unavailable","other"]},{"type":"null"}],"title":"Failure Reason","description":"Why the scan failed, one of `stuck_no_progress`, `brief_abandoned`, `insufficient_engine_signal`, `cost_cap_exceeded`, `report_inputs_missing`, `service_unavailable` or `other`; null unless the scan failed. New values may be added."},"heralded_score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Heralded Score","description":"The Heralded Score the scan issued. Null while it runs or is partial, on a daily scan, which issues none, and where its answers measured none."},"heralded_score_band":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Heralded Score Band","description":"The band `heralded_score` falls in; null without a score.","readOnly":true}},"type":"object","required":["id","kind","state","domain","market","started_at","completed_at","share_id","report_url","progress_pct","failure_reason","heralded_score","heralded_score_band"],"title":"V1ScanRow"},"V1Scans":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"scans":{"items":{"$ref":"#/components/schemas/V1ScanRow"},"type":"array","title":"Scans"}},"type":"object","required":["meta","next_cursor","total","limit","offset","scans"],"title":"V1Scans","examples":[{"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"scans":[],"total":0}]},"V1ScoreContext":{"properties":{"brand_name":{"type":"string","title":"Brand Name"},"prompts":{"type":"integer","title":"Prompts"},"engines":{"type":"integer","title":"Engines"},"answers":{"type":"integer","title":"Answers"},"first_answer_at":{"type":"string","format":"date-time","title":"First Answer At"},"last_answer_at":{"type":"string","format":"date-time","title":"Last Answer At"}},"type":"object","required":["brand_name","prompts","engines","answers","first_answer_at","last_answer_at"],"title":"V1ScoreContext","description":"What the latest weekly scan's Heralded Score was read from."},"V1ScoreGroup":{"properties":{"engine":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Engine"},"intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent"},"stage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stage"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"topic":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Topic"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"prompt":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Prompt"},"competitor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Competitor"},"brand_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Name"},"is_you":{"type":"boolean","title":"Is You","default":false}},"type":"object","required":["engine","intent","stage","type","topic","country","prompt","competitor","brand_name","is_you"],"title":"V1ScoreGroup","description":"What one group of `groups` is: the value of the dimension `group_by`\nnames, the others null. A competitor group names the brand, and\n`is_you` marks the brand's own."},"V1ScoreRow":{"properties":{"group":{"$ref":"#/components/schemas/V1ScoreGroup"},"prompt_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompt Count","description":"Prompts represented by this row under the selected filters."},"heralded_score":{"$ref":"#/components/schemas/V1Figure"},"mentioned":{"$ref":"#/components/schemas/V1Figure"},"recommended":{"$ref":"#/components/schemas/V1Figure"},"understood":{"$ref":"#/components/schemas/V1Figure"},"praised":{"$ref":"#/components/schemas/V1Figure"}},"type":"object","required":["group","prompt_count","heralded_score","mentioned","recommended","understood","praised"],"title":"V1ScoreRow"},"V1Scores":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"period":{"$ref":"#/components/schemas/V1Period"},"sides_available":{"items":{"type":"string","enum":["ai","search"]},"type":"array","title":"Sides Available","description":"The sides the period's reports observed: `ai`, and `search` once a report checked keywords. A read of reports without search observations states `[\"ai\"]`, and `all` is then the AI side."},"heralded_score":{"$ref":"#/components/schemas/V1Figure"},"mentioned":{"$ref":"#/components/schemas/V1Figure"},"recommended":{"$ref":"#/components/schemas/V1Figure"},"understood":{"$ref":"#/components/schemas/V1Figure"},"praised":{"$ref":"#/components/schemas/V1Figure"},"engine_weights":{"additionalProperties":{"type":"number"},"type":"object","title":"Engine Weights","description":"Each engine's configured share of the AI side, from 0 to 1. Unchanged by filters."},"side_weights":{"additionalProperties":{"type":"number"},"propertyNames":{"enum":["ai","search"]},"type":"object","title":"Side Weights","description":"Each side's share of All, from 0 to 1. AI is 1 and Search is 0 while Search is not scored. Unchanged by filters or availability."},"groups":{"anyOf":[{"items":{"$ref":"#/components/schemas/V1ScoreRow"},"type":"array"},{"type":"null"}],"title":"Groups"},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headline","description":"One sentence on how AI answers treat the brand under this read's filters, from templates with no model call. Null on `side=search`, before the first read and while no figure is measured."},"competitor_rank":{"anyOf":[{"$ref":"#/components/schemas/V1CompetitorRank"},{"type":"null"}],"description":"Under `group_by=competitor`, your rank by Heralded Score among the tracked competitors in `groups`; null otherwise, or while your score or every competitor's is unmeasured."},"panes":{"anyOf":[{"items":{"$ref":"#/components/schemas/V1AxisPane"},"type":"array"},{"type":"null"}],"title":"Panes"},"pane_prompts":{"items":{"$ref":"#/components/schemas/PerceptionPromptRow"},"type":"array","title":"Pane Prompts"},"pane_rivals":{"items":{"$ref":"#/components/schemas/RivalAxes"},"type":"array","title":"Pane Rivals"},"engines":{"anyOf":[{"$ref":"#/components/schemas/EnginesPage"},{"type":"null"}]},"engine":{"anyOf":[{"$ref":"#/components/schemas/V1EnginePane"},{"type":"null"}]}},"type":"object","required":["meta","next_cursor","period","sides_available","heralded_score","mentioned","recommended","understood","praised","engine_weights","side_weights","groups","headline","competitor_rank","panes","pane_prompts","pane_rivals","engines","engine"],"title":"V1Scores"},"V1ScreenCheck":{"properties":{"verdict":{"type":"string","enum":["pass","fail","unsure"],"title":"Verdict"},"why":{"type":"string","title":"Why"}},"type":"object","required":["verdict","why"],"title":"V1ScreenCheck"},"V1SearchBrand":{"properties":{"brand_key":{"type":"string","title":"Brand Key","description":"The key that opens the brand's competitor page."},"name":{"type":"string","title":"Name","description":"The tracked brand's name."},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"The brand's domain, when known."},"is_you":{"type":"boolean","title":"Is You","description":"Whether this is your brand."},"rank":{"type":"integer","title":"Rank","description":"1-based place by the axis value. On Search it is a position with unmeasured brands last; on AI answers brands on one value share a place."},"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value","description":"The brand's axis value in whole points."},"change":{"anyOf":[{"$ref":"#/components/schemas/V1Change"},{"type":"null"}],"description":"The axis change under the selected filters."}},"type":"object","required":["brand_key","name","domain","is_you","rank","value","change"],"title":"V1SearchBrand"},"V1SearchMarket":{"properties":{"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"The market's country; null means Global."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Its keywords' language; null for a country searched in more than one."},"rankings":{"type":"integer","title":"Rankings","description":"Tracked rankings in this country, checked or not: the keywords read's `total` with `market` set to it."},"figure":{"$ref":"#/components/schemas/V1Figure","description":"The Search axis over this country's checks, as the keywords read's summary under its `market`, with no trend."}},"type":"object","required":["country","language","rankings","figure"],"title":"V1SearchMarket"},"V1SearchPaneDetail":{"properties":{"rankings_total":{"type":"integer","title":"Rankings Total","description":"Every tracked ranking, checked or not: the keywords read's `keyword_markets_total`."},"rankings_checked":{"type":"integer","title":"Rankings Checked","description":"Those rankings with a fetched check in the period: the keywords read's `rankings_total`."},"rankings_on_axis":{"type":"integer","title":"Rankings On Axis","description":"Those rankings whose latest check has a positive axis share: the keywords read's `total` with `mentions` set to the axis."},"rankings_checked_on_axis":{"type":"integer","title":"Rankings Checked On Axis","description":"Those of `rankings_checked` whose latest check has a positive axis share: the keywords read's `rankings_total` with `mentions` set to the axis."},"own_pages_top10":{"type":"integer","title":"Own Pages Top10","description":"Number of distinct own canonical pages in the rankings' latest checks."},"ai_overviews_citing_you":{"type":"integer","title":"Ai Overviews Citing You","description":"Number of rankings whose latest check's AI Overview cites you."},"brands":{"items":{"$ref":"#/components/schemas/V1SearchBrand"},"type":"array","title":"Brands","description":"Brands by axis value, unmeasured last, with 1-based ranks. Compact previews show five with you included; section=brands uses limit and offset. brands_total counts the complete selection."},"brands_total":{"type":"integer","title":"Brands Total","description":"The scoped Competitors board's total, including you."},"brands_led":{"type":"integer","title":"Brands Led","description":"Brands with an axis value below yours; 0 while yours is not measured."},"rankings":{"items":{"$ref":"#/components/schemas/V1SearchRanking"},"type":"array","title":"Rankings","description":"Rankings by period value, volume, then text. Five by default; section=rankings uses limit and offset. rankings_on_axis counts every matching ranking."},"ranking_pages":{"items":{"$ref":"#/components/schemas/V1SearchRankingPage"},"type":"array","title":"Ranking Pages","description":"Own pages in the latest top ten, by best rank, volume, then URL. Compact previews show five; section=ranking_pages uses limit and offset. own_pages_top10 counts the complete selection."},"by_market":{"items":{"$ref":"#/components/schemas/V1SearchMarket"},"type":"array","title":"By Market","description":"Countries by ranking count, then country, with Global last on ties. Omitted from compact previews until section=markets requests a limit/offset page. by_market_total counts the complete selection."},"by_market_total":{"type":"integer","title":"By Market Total","description":"All markets represented in the selected rankings before paging.","default":0},"next_step":{"anyOf":[{"$ref":"#/components/schemas/V1PaneAction"},{"type":"null"}],"description":"The highest-priority eligible work item across the subject’s entire live work selection, or null."},"actions":{"items":{"$ref":"#/components/schemas/V1PaneAction"},"type":"array","title":"Actions","description":"Live actions about these rankings or your pages, by priority. Three by default; section=work uses limit and offset. actions_total counts all live work."},"actions_total":{"type":"integer","title":"Actions Total","description":"Total live actions targeting these rankings or their own pages."}},"type":"object","required":["rankings_total","rankings_checked","rankings_on_axis","rankings_checked_on_axis","own_pages_top10","ai_overviews_citing_you","brands","brands_total","brands_led","rankings","ranking_pages","by_market","by_market_total","actions","actions_total"],"title":"V1SearchPaneDetail"},"V1SearchRanking":{"properties":{"keyword_id":{"type":"string","format":"uuid","title":"Keyword Id","description":"The tracked keyword's identity."},"text":{"type":"string","title":"Text","description":"The words searched on Google."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"The check's country; null means Global."},"language":{"type":"string","title":"Language","description":"The keyword's search language."},"searches_mo":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Searches Mo","description":"Monthly searches for this keyword in its market."},"volume_state":{"type":"string","title":"Volume State","description":"The keyword's volume state, as the keywords read serves it.","x-extensible-enum":["pending","measured","unavailable","zero","no_data"]},"best_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Rank","description":"Your best position in the latest check's top 10."},"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value","description":"The keyword's axis value over the selected period."}},"type":"object","required":["keyword_id","text","country","language","searches_mo","volume_state","best_rank","value"],"title":"V1SearchRanking"},"V1SearchRankingPage":{"properties":{"url":{"type":"string","title":"Url","description":"Your page's canonical URL."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The title saved with its best ranking result."},"best_rank":{"type":"integer","title":"Best Rank","description":"The page's best position among the latest checks' top 10."},"keyword_id":{"type":"string","format":"uuid","title":"Keyword Id","description":"The keyword where this page holds its best rank."},"keyword_text":{"type":"string","title":"Keyword Text","description":"The words searched for that best rank."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"That ranking's country; null means Global."},"rankings":{"type":"integer","title":"Rankings","description":"Number of checked rankings containing this canonical page."}},"type":"object","required":["url","title","best_rank","keyword_id","keyword_text","country","rankings"],"title":"V1SearchRankingPage"},"V1SearchSummary":{"properties":{"mentioned":{"$ref":"#/components/schemas/V1Figure","description":"Search Mentioned over the selection, with change and weekly trend."},"figures":{"additionalProperties":{"$ref":"#/components/schemas/V1Figure"},"type":"object","title":"Figures","description":"Card values with their weekly report windows and served changes."},"markets":{"type":"integer","title":"Markets","description":"Distinct country and language pairs in the selection."},"positions":{"$ref":"#/components/schemas/PositionCounts","description":"Position bands summing to keyword_markets_total."},"top_10":{"type":"integer","title":"Top 10","description":"Keywords ranked 1 to 10 in the selection."},"checked_top_3":{"type":"integer","title":"Checked Top 3","description":"Keywords checked in the period whose latest rank is 1 to 3, out of rankings_total."},"checked_top_10":{"type":"integer","title":"Checked Top 10","description":"Keywords checked in the period whose latest rank is 1 to 10, out of rankings_total."}},"type":"object","required":["mentioned","figures","markets","positions","top_10","checked_top_3","checked_top_10"],"title":"V1SearchSummary"},"V1SeriesPoint":{"properties":{"run_number":{"type":"integer","title":"Run Number"},"completed_at":{"type":"string","format":"date-time","title":"Completed At"},"value":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"null"}],"title":"Value"},"degraded":{"type":"boolean","title":"Degraded","description":"An engine was dropped from this scan: it measured less, not worse."},"break":{"anyOf":[{"$ref":"#/components/schemas/TrendBreak"},{"type":"null"}],"readOnly":true}},"type":"object","required":["run_number","completed_at","value","degraded","break"],"title":"V1SeriesPoint"},"V1Settings":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"brand_id":{"type":"string","format":"uuid","title":"Brand Id"},"deletion_scheduled_for":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deletion Scheduled For"},"name":{"type":"string","title":"Name"},"domain":{"type":"string","title":"Domain"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"prompts_used":{"type":"integer","title":"Prompts Used","description":"Active prompts of the brand's active topics in live segments. A paused brand keeps this count while spending no organization slots."},"prompts_reserved":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompts Reserved","description":"Always null: no brand reserves prompts, segments are the unit allocated."},"profile":{"$ref":"#/components/schemas/BrandProfilePage"},"owned_domains":{"$ref":"#/components/schemas/OwnedDomainsDraft"},"autonomy":{"$ref":"#/components/schemas/AutonomyPayload"},"connections":{"items":{"$ref":"#/components/schemas/V1ConnectionStatus"},"type":"array","title":"Connections"},"features":{"$ref":"#/components/schemas/PlanFeatures"}},"type":"object","required":["meta","brand_id","deletion_scheduled_for","name","domain","description","prompts_used","prompts_reserved","profile","owned_domains","autonomy","connections","features"],"title":"V1Settings"},"V1ShareOfVoice":{"properties":{"population":{"type":"string","enum":["all_answers","weekly_answers","search_keywords"],"title":"Population"},"answers":{"type":"integer","title":"Answers"},"excluded_answers":{"type":"integer","title":"Excluded Answers"},"state":{"type":"string","enum":["measured","not_measured","not_comparable"],"title":"State"},"rows":{"items":{"$ref":"#/components/schemas/V1VoiceShare"},"type":"array","title":"Rows"}},"type":"object","required":["population","answers","excluded_answers","state","rows"],"title":"V1ShareOfVoice"},"V1SharedAnswer":{"properties":{"engine":{"type":"string","title":"Engine","description":"The engine that answered the question."},"run":{"type":"integer","title":"Run","description":"The answer's position within its engine across the whole question, starting at 1, in frozen answer order."},"mark":{"$ref":"#/components/schemas/VocabularyOption","description":"The served strength rung for your brand."},"excerpt":{"type":"string","maxLength":600,"title":"Excerpt","description":"Up to 600 characters, with hidden names masked."},"highlights":{"items":{"$ref":"#/components/schemas/AnswerHighlightSpan"},"type":"array","title":"Highlights","description":"Half-open Unicode code-point spans in the excerpt for your brand and rivals."},"text":{"type":"string","title":"Text","description":"The full retained answer as Markdown, with hidden names masked, including link URLs."},"text_highlights":{"items":{"$ref":"#/components/schemas/AnswerHighlightSpan"},"type":"array","title":"Text Highlights","description":"Half-open Unicode code-point spans in text for your brand and rivals."},"brands":{"items":{"$ref":"#/components/schemas/V1SharedAnswerBrand"},"type":"array","title":"Brands","description":"Visible brands this answer names."},"cited_urls":{"items":{"type":"string"},"type":"array","title":"Cited Urls","description":"Cited URLs that do not name hidden competitors."},"text_retained":{"type":"boolean","title":"Text Retained","description":"Whether the original answer text is still retained."}},"type":"object","required":["engine","run","mark","excerpt","highlights","text","text_highlights","brands","cited_urls","text_retained"],"title":"V1SharedAnswer"},"V1SharedAnswerBrand":{"properties":{"name":{"type":"string","title":"Name","description":"A brand named in the answer and visible in the shared report."},"mark":{"$ref":"#/components/schemas/VocabularyOption","description":"How the answer treats this brand."}},"type":"object","required":["name","mark"],"title":"V1SharedAnswerBrand"},"V1SharedAnswers":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total","description":"Rendered answers to this question in the report."},"limit":{"type":"integer","title":"Limit","description":"Answers per page, fixed at 10."},"offset":{"type":"integer","title":"Offset","description":"Answers preceding this page."},"answers":{"items":{"$ref":"#/components/schemas/V1SharedAnswer"},"type":"array","title":"Answers","description":"This page's answers in frozen report order."},"brands":{"items":{"$ref":"#/components/schemas/V1SharedQuestionBrand"},"type":"array","title":"Brands","description":"Shown brands across the whole question."},"pages":{"items":{"$ref":"#/components/schemas/V1SharedQuestionPage"},"type":"array","title":"Pages","description":"Visible cited pages across the whole question."}},"type":"object","required":["meta","next_cursor","total","limit","offset","answers","brands","pages"],"title":"V1SharedAnswers","examples":[{"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"total":1,"limit":10,"offset":0,"next_cursor":null,"answers":[{"engine":"openai","run":1,"mark":{"value":"mentioned","label":"Mentioned"},"excerpt":"Acme is one option.","highlights":[{"start":0,"end":4,"brand":"you"}],"text":"Acme is one option.","text_highlights":[{"start":0,"end":4,"brand":"you"}],"brands":[{"name":"Acme","mark":{"value":"mentioned","label":"Mentioned"}}],"cited_urls":["https://acme.com/"],"text_retained":true}],"brands":[{"name":"Acme","answers":1}],"pages":[{"url":"https://acme.com/","answers":1}]}]},"V1SharedAudit":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"share_id":{"type":"string","format":"uuid","title":"Share Id"},"domain":{"type":"string","title":"Domain"},"website":{"anyOf":[{"$ref":"#/components/schemas/V1Website"},{"type":"null"}]},"key_pages":{"items":{"$ref":"#/components/schemas/V1KeyPage"},"type":"array","title":"Key Pages"},"map":{"$ref":"#/components/schemas/V1SiteMap"}},"type":"object","required":["meta","share_id","domain","website","key_pages","map"],"title":"V1SharedAudit"},"V1SharedEngineSite":{"properties":{"domain":{"type":"string","title":"Domain","description":"A visible cited site's host, without www."},"citation_count":{"type":"integer","title":"Citation Count","description":"Cited pages across the engine's rendered answers. A page counts once per answer."}},"type":"object","required":["domain","citation_count"],"title":"V1SharedEngineSite"},"V1SharedEngineSites":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"sites":{"items":{"$ref":"#/components/schemas/V1SharedEngineSite"},"type":"array","title":"Sites","description":"Visible sites cited by this engine, most citations first."}},"type":"object","required":["meta","sites"],"title":"V1SharedEngineSites"},"V1SharedProduct":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"product":{"$ref":"#/components/schemas/ShoppingProduct","description":"The product as the report shows it: figures, engines, questions (`questions_total` before paging) and products shown beside it."},"maker_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Maker Key","description":"The canonical key of its maker, as `brand_keys` serves it."}},"type":"object","required":["meta","product","maker_key"],"title":"V1SharedProduct","description":"A product's details from a shared report."},"V1SharedProducts":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total","description":"Products the report may name in this scope, before paging. Counts of `hidden_products` are apart."},"limit":{"type":"integer","title":"Limit","description":"The page's maximum rows."},"offset":{"type":"integer","title":"Offset","description":"Rows skipped before this page."},"products":{"items":{"$ref":"#/components/schemas/SharedProductRow"},"type":"array","title":"Products","description":"One page of products, most shown first. Each carries its figures in this scope, its maker, price and seller."},"hidden_products":{"type":"integer","title":"Hidden Products","description":"Products in this scope of brands the report does not show. They are counted, never listed, and have no details to read."},"hidden_brands":{"type":"integer","title":"Hidden Brands","description":"The brands the report does not show behind `hidden_products`."}},"type":"object","required":["meta","next_cursor","total","limit","offset","products","hidden_products","hidden_brands"],"title":"V1SharedProducts","description":"The complete list of products a shared report's question or brand holds.","examples":[{"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"total":1,"limit":20,"offset":0,"next_cursor":null,"hidden_products":3,"hidden_brands":2,"products":[{"id":"6f1d2c1e-6c5a-4a8e-9a43-0d3f4c7b9e10","name":"Acme Talus GTX","url":null,"yours":true,"maker":null,"maker_key":"acme","shown":{"value":0.5,"low":0.1,"high":0.9,"numerator":1,"denominator":2},"answers_shown":1,"average_position":1.0,"best_position":1,"seller_is_your_shop":null,"price_matches_your_shop":null,"offer":null}]}]},"V1SharedQuestionBrand":{"properties":{"name":{"type":"string","title":"Name","description":"A brand shown in the shared report."},"answers":{"type":"integer","title":"Answers","description":"Answers to the whole question naming this visible brand."}},"type":"object","required":["name","answers"],"title":"V1SharedQuestionBrand"},"V1SharedQuestionPage":{"properties":{"url":{"type":"string","title":"Url","description":"A cited page's address without campaign tracking parameters."},"answers":{"type":"integer","title":"Answers","description":"Answers to the whole question citing this page."}},"type":"object","required":["url","answers"],"title":"V1SharedQuestionPage"},"V1SharedScan":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"market":{"anyOf":[{"$ref":"#/components/schemas/ReportMarket"},{"type":"null"}],"description":"The report's stored \"Your market\" figures and constants version. Google measurements and the ChatGPT estimate remain separate."},"shopping":{"anyOf":[{"$ref":"#/components/schemas/ReportShopping"},{"type":"null"}],"description":"An ecommerce report's stored \"Your products in AI shopping\" and \"Ready for AI shopping\" sections: product cards in the answers, product page checks and Google Shopping placement. Null on a report not measured as ecommerce."},"competitor_evidence":{"items":{"$ref":"#/components/schemas/ReportCompetitorEvidence"},"type":"array","title":"Competitor Evidence","description":"Each visible brand's unbranded wins, engine figures and citing sources. Null evidence lists were not measured; empty lists were measured without a result."},"missing_question":{"anyOf":[{"$ref":"#/components/schemas/RivalQuestion"},{"type":"null"}],"description":"The unbranded question the strongest scored competitor was named for most often while you went unnamed, naming you in fewer than half its answers. Null when no question qualifies. Tied competitors follow name order; tied questions follow the order asked."},"found_competitors_more":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Found Competitors More","description":"How many more competitors the answers named than `competitor_final_score` shows. Set on a Snapshot, whose competitors are the ones its answers named most; null elsewhere. Their names are not served."},"share_id":{"type":"string","format":"uuid","title":"Share Id"},"partial":{"type":"boolean","title":"Partial","description":"Delivered before every answer came back; the report fills in until final."},"change_token":{"type":"string","title":"Change Token","description":"Moves when the scan's measurements are rewritten."},"async_change_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Async Change Token","description":"Moves when analysis, owned content or share cards land."},"interpretation_status":{"anyOf":[{"type":"string","enum":["ready","processing","failed","unavailable"]},{"type":"null"}],"title":"Interpretation Status"},"readiness_status":{"anyOf":[{"type":"string","enum":["ready","processing","failed","unavailable"]},{"type":"null"}],"title":"Readiness Status","description":"Processing while a late site-check read can still change the report."},"engine_vocabulary":{"items":{"$ref":"#/components/schemas/EngineVocabulary"},"type":"array","title":"Engine Vocabulary"},"engine_coverage":{"anyOf":[{"items":{"$ref":"#/components/schemas/EngineCoverage"},"type":"array"},{"type":"null"}],"title":"Engine Coverage"},"moves":{"items":{"$ref":"#/components/schemas/RenderedMove"},"type":"array","title":"Moves","description":"The work Heralded's plays would file for this scan, best first: at most 5, at most 2 of one play, none below a medium expected gain."},"scan":{"$ref":"#/components/schemas/ReportScanResponse"},"brand_profile":{"anyOf":[{"$ref":"#/components/schemas/BrandProfileResponse"},{"type":"null"}]},"claims":{"additionalProperties":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"type":"object","title":"Claims","description":"The report's sections by claim type: competitor_final_score, discovered_competitors, matrix_cell, positioning_quadrant, positioning_statement, rival_framing, sentiment_signal, source_relationship, spicy_zinger, suggested_prompt, understanding_row, understanding_summary"},"share_cards":{"additionalProperties":{"type":"string"},"type":"object","title":"Share Cards","description":"Each share card's image URL by variant. `preview` is the 1200×630 image a pasted report link shows; the other cards are 1200×1200."},"share_cards_enabled":{"type":"boolean","title":"Share Cards Enabled"},"pdf_enabled":{"type":"boolean","title":"Pdf Enabled","description":"Whether this run delivers a Snapshot PDF.","default":false},"source_tier_rollups":{"items":{"$ref":"#/components/schemas/SourceTierRollup"},"type":"array","title":"Source Tier Rollups"},"brand_citation_summary":{"anyOf":[{"$ref":"#/components/schemas/BrandCitationSummary"},{"type":"null"}]},"strength_tiers":{"items":{"$ref":"#/components/schemas/VocabularyOption"},"type":"array","title":"Strength Tiers"},"intents":{"items":{"$ref":"#/components/schemas/VocabularyOption"},"type":"array","title":"Intents"},"source_tiers":{"items":{"$ref":"#/components/schemas/SourceTierOption"},"type":"array","title":"Source Tiers"},"answers_citing_you":{"anyOf":[{"$ref":"#/components/schemas/CitationMetric"},{"type":"null"}]},"sources_mentioning_you":{"anyOf":[{"$ref":"#/components/schemas/CitationMetric"},{"type":"null"}]},"positioning":{"items":{"$ref":"#/components/schemas/ReportPositioningAxis"},"type":"array","title":"Positioning"},"pro_extras":{"anyOf":[{"$ref":"#/components/schemas/ProReportExtras"},{"type":"null"}]},"previous_runs":{"items":{"$ref":"#/components/schemas/ReportRun"},"type":"array","title":"Previous Runs","description":"The runs this link served before its re-runs, newest first."},"newer_runs":{"items":{"$ref":"#/components/schemas/ReportRun"},"type":"array","title":"Newer Runs","description":"The delivered re-runs of this scan, newest first."}},"type":"object","required":["meta","market","shopping","competitor_evidence","missing_question","found_competitors_more","share_id","partial","change_token","async_change_token","interpretation_status","readiness_status","engine_vocabulary","engine_coverage","moves","scan","brand_profile","claims","share_cards","share_cards_enabled","pdf_enabled","source_tier_rollups","brand_citation_summary","strength_tiers","intents","source_tiers","answers_citing_you","sources_mentioning_you","positioning","pro_extras","previous_runs","newer_runs"],"title":"V1SharedScan"},"V1SideFigures":{"properties":{"heralded_score":{"$ref":"#/components/schemas/V1Figure"},"mentioned":{"$ref":"#/components/schemas/V1Figure"},"recommended":{"$ref":"#/components/schemas/V1Figure"},"understood":{"$ref":"#/components/schemas/V1Figure","description":"Understood on this side."},"praised":{"$ref":"#/components/schemas/V1Figure","description":"Praised on this side."}},"type":"object","required":["heralded_score","mentioned","recommended","understood","praised"],"title":"V1SideFigures"},"V1Sides":{"properties":{"all":{"$ref":"#/components/schemas/V1SideFigures"},"ai":{"$ref":"#/components/schemas/V1SideFigures"},"search":{"$ref":"#/components/schemas/V1SideFigures"}},"type":"object","required":["all","ai","search"],"title":"V1Sides"},"V1SinceStarted":{"properties":{"first":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"First","description":"The first weekly scan's score; null once the first scans are pooled."},"first_report_at":{"type":"string","format":"date-time","title":"First Report At"},"current":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Current"},"series":{"items":{"$ref":"#/components/schemas/V1SeriesPoint"},"type":"array","title":"Series","description":"The score per weekly scan, oldest first."},"third_report_due_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Third Report Due At","description":"When the third weekly scan runs, which starts the trend; null from then on."}},"type":"object","required":["first","first_report_at","current","series","third_report_due_at"],"title":"V1SinceStarted","description":"The Heralded Score's move since the brand's first weekly scan."},"V1SiteMap":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"state":{"type":"string","enum":["complete","pending","unavailable"],"title":"State"},"fully_read":{"type":"boolean","title":"Fully Read","description":"The run read the whole site, with no sampled or truncated discovery; false when the stored graph has no flag.","default":false},"site":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Site"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"languages":{"items":{"$ref":"#/components/schemas/V1WebsiteLanguage"},"type":"array","title":"Languages"},"counts":{"anyOf":[{"$ref":"#/components/schemas/V1MapCounts"},{"type":"null"}],"description":"Over every page in the language."},"folders":{"items":{"$ref":"#/components/schemas/V1MapFolder"},"type":"array","title":"Folders","description":"The folders under folder, or under /."},"pages":{"items":{"$ref":"#/components/schemas/V1MapPage"},"type":"array","title":"Pages"},"citations":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"title":"Citations","description":"Positive citation counts keyed by the listed pages' URLs, from the same pinned weekly report; null without complete citation measurements."},"pages_total":{"type":"integer","title":"Pages Total","description":"The pages before folder_pages_limit cuts them."},"site_pages":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Site Pages","description":"Pages on the site in every language, the Website read's coverage.pages for the same run; null with no map."},"links":{"items":{"$ref":"#/components/schemas/V1MapLink"},"type":"array","title":"Links","description":"Links between the pages listed."},"categories":{"items":{"$ref":"#/components/schemas/V1MapCategory"},"type":"array","title":"Categories"},"collections":{"items":{"$ref":"#/components/schemas/V1MapCollection"},"type":"array","title":"Collections"},"archives":{"items":{"$ref":"#/components/schemas/V1MapArchive"},"type":"array","title":"Archives"},"unrecorded":{"type":"integer","title":"Unrecorded"},"findings":{"items":{"$ref":"#/components/schemas/V1MapFinding"},"type":"array","title":"Findings"},"folder_pages_total":{"type":"integer","title":"Folder Pages Total","description":"All pages in this folder before paging.","readOnly":true}},"type":"object","required":["meta","state","fully_read","site","language","languages","counts","folders","pages","citations","pages_total","site_pages","links","categories","collections","archives","unrecorded","findings","folder_pages_total"],"title":"V1SiteMap","description":"A run's frozen map in one language: its pages, the links between them\nand what each holds back. With folder, that folder's pages and the\nfolders under it."},"V1SitePages":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headline","description":"Templated headline over the served page access and findings counts."},"readable":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Readable","description":"Pages AI can read under the active filters, before paging."},"with_findings":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"With Findings","description":"Pages with findings under the filters; null if any page was not measured."},"cited":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cited","description":"Cited pages under the filters; null without complete citations."},"state":{"type":"string","enum":["ready","awaiting_first_crawl","unavailable"],"title":"State"},"facets":{"$ref":"#/components/schemas/AuditFacets","description":"Each category with the pages every filter but category leaves, and each language with the pages every filter leaves."},"crawler_hits_available":{"type":"boolean","title":"Crawler Hits Available"},"crawler_hits_days":{"type":"integer","title":"Crawler Hits Days"},"citations_scan":{"anyOf":[{"$ref":"#/components/schemas/DataAsOf"},{"type":"null"}],"description":"The last weekly scan, whose answers the pages' citations count."},"pages":{"items":{"$ref":"#/components/schemas/V1AuditPage"},"type":"array","title":"Pages"}},"type":"object","required":["meta","next_cursor","total","limit","offset","headline","readable","with_findings","cited","state","facets","crawler_hits_available","crawler_hits_days","citations_scan","pages"],"title":"V1SitePages","examples":[{"headline":null,"readable":null,"with_findings":null,"cited":null,"citations_scan":null,"crawler_hits_available":false,"crawler_hits_days":0,"facets":{"categories":[],"languages":[]},"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"pages":[],"state":"ready","total":0}]},"V1SiteScope":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"scopes":{"items":{"$ref":"#/components/schemas/ScopeEntry"},"type":"array","title":"Scopes"},"pages_in_site":{"type":"integer","minimum":0.0,"title":"Pages In Site","default":0}},"type":"object","required":["meta","next_cursor","total","limit","offset","scopes","pages_in_site"],"title":"V1SiteScope","examples":[{"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"pages_in_site":0,"scopes":[],"total":0}]},"V1Snapshot":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"id":{"type":"string","format":"uuid","title":"Id","description":"The scan's id."},"kind":{"type":"string","enum":["weekly","daily","snapshot","audit"],"title":"Kind","description":"`weekly`, `daily`, `snapshot` (a one-time Snapshot or a brand's first) or `audit`."},"state":{"type":"string","enum":["preparing","running","completed","failed","expired"],"title":"State","description":"`preparing` while the profile drafts or waits for Run, `running`, `completed`, `failed`, or `expired`: a Snapshot whose profile waited 24 hours without a run."},"partial":{"type":"boolean","title":"Partial","description":"A Snapshot delivered before every answer came back, still filling in."},"brand_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Brand Id","description":"Null for a Snapshot no brand holds."},"domain":{"type":"string","title":"Domain","description":"The site the scan measured."},"sells_to":{"type":"string","enum":["businesses","consumers"],"title":"Sells To","description":"Who the scan measured the brand as selling to: `businesses` or `consumers`. Fixed for the scan once it runs."},"ecommerce":{"type":"boolean","title":"Ecommerce","description":"Whether the scan measured the brand as ecommerce, which reads product cards and Google Shopping. Fixed for the scan once it runs."},"started_at":{"type":"string","format":"date-time","title":"Started At","description":"When the scan was started."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When it completed, failed or expired; null until then."},"questions_asked":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Questions Asked","description":"How many questions the scan asks AI engines. A Snapshot asks 20, or 12 to 19 when fewer of its drafted questions passed review. Null before its questions are fixed and on an Audit."},"profile":{"anyOf":[{"$ref":"#/components/schemas/V1SnapshotProfile"},{"type":"null"}],"description":"A preparing Snapshot's profile, to confirm or edit before Run; null while it drafts and once the Snapshot runs."},"run_request":{"anyOf":[{"$ref":"#/components/schemas/V1RunRequest"},{"type":"null"}],"description":"Run pressed before the Snapshot started; null otherwise."},"payer":{"anyOf":[{"$ref":"#/components/schemas/V1SnapshotPayer"},{"type":"null"}],"description":"Who pays for a Snapshot: recorded on Run, charged when it starts. A run that needs action keeps the payer it waits on. Null before Run, after a stop and on other scans."},"share_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Share Id","description":"The report link id once delivered; null on a daily scan and before delivery. Quick shares use /v1/shared/audits/{share_id}; Base and Full remain owner-only."},"report_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Url","description":"A delivered Snapshot's or weekly scan's report page, to give the member; null on an Audit, a daily scan and before delivery."},"progress":{"anyOf":[{"$ref":"#/components/schemas/V1ScanProgress"},{"type":"null"}],"description":"Null on an Audit and once the scan completed or failed."},"audit_progress":{"anyOf":[{"$ref":"#/components/schemas/AuditProgress"},{"type":"null"}],"description":"An Audit's live page and screenshot counts; null on other scans."},"failure_reason":{"anyOf":[{"type":"string","x-extensible-enum":["stuck_no_progress","brief_abandoned","insufficient_engine_signal","cost_cap_exceeded","report_inputs_missing","service_unavailable","other"]},{"type":"null"}],"title":"Failure Reason","description":"Why the scan failed, one of `stuck_no_progress`, `brief_abandoned`, `insufficient_engine_signal`, `cost_cap_exceeded`, `report_inputs_missing`, `service_unavailable` or `other`; null unless the scan failed. New values may be added."},"issued":{"anyOf":[{"$ref":"#/components/schemas/V1ScanFacts"},{"type":"null"}],"description":"What the scan issued once complete; null while it runs, while it is partial, on a daily scan and on an Audit."},"url":{"type":"string","title":"Url","description":"The Snapshot's page, where its member can check the profile, run it and follow it."}},"type":"object","required":["meta","id","kind","state","partial","brand_id","domain","sells_to","ecommerce","started_at","completed_at","questions_asked","profile","run_request","payer","share_id","report_url","progress","audit_progress","failure_reason","issued","url"],"title":"V1Snapshot"},"V1SnapshotFigures":{"properties":{"heralded_score":{"anyOf":[{"$ref":"#/components/schemas/V1IssuedScore"},{"type":"null"}],"description":"The Heralded Score this Snapshot issued."},"mentioned":{"anyOf":[{"$ref":"#/components/schemas/V1IssuedRate"},{"type":"null"}],"description":"Mentioned, ranked among this Snapshot's rivals."},"recommended":{"anyOf":[{"$ref":"#/components/schemas/V1IssuedRate"},{"type":"null"}],"description":"Recommended, ranked among this Snapshot's rivals."}},"type":"object","required":["heralded_score","mentioned","recommended"],"title":"V1SnapshotFigures"},"V1SnapshotPayer":{"properties":{"by":{"type":"string","enum":["free_snapshot","credits"],"title":"By","description":"`free_snapshot`: the member's free Snapshot. `credits`: the organization's Snapshot credits."},"organization_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Organization Id","description":"The organization whose credits pay; null for a free Snapshot."}},"type":"object","required":["by","organization_id"],"title":"V1SnapshotPayer"},"V1SnapshotProfile":{"properties":{"brand_name":{"type":"string","title":"Brand Name","description":"The brand the Snapshot measures."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"What the brand does, in a sentence."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"The market category drafted for the brand."},"buyer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer","description":"Who buys from the brand, from the drafted target buyer."},"competitors":{"items":{"type":"string"},"type":"array","title":"Competitors","description":"Competitor names drafted for the Snapshot so far. Read-only: a Snapshot ranks the competitors its AI answers name. Empty while they are still drafting."},"market":{"type":"string","title":"Market","description":"Where AI engines are asked: `global`, `europe` or a country code such as `US`."}},"type":"object","required":["brand_name","description","category","buyer","competitors","market"],"title":"V1SnapshotProfile","description":"The profile a Snapshot measures, which its member confirms before Run."},"V1SnapshotShare":{"properties":{"share_url":{"type":"string","title":"Share Url","description":"The unlisted Snapshot URL, which opens signed out."}},"type":"object","required":["share_url"],"title":"V1SnapshotShare"},"V1Source":{"properties":{"verdict":{"type":"string","enum":["recommends_you","names_you","not_named","unread"],"title":"Verdict","description":"Strongest verdict from the pages AI cites on this site.","default":"unread"},"opening":{"type":"boolean","title":"Opening","description":"A pitchable opportunity whose cited pages do not name you.","default":false},"found_via":{"items":{"type":"string","enum":["ai_citation","google_ranking","monitor"]},"type":"array","title":"Found Via"},"recommends_you":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Recommends You"},"read_by_searchers":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Read By Searchers","description":"Estimated monthly readers from tracked keyword volume and ranking click shares, averaged over checks in the period. Never sum across sites. Null when search demand is unavailable."},"placements":{"anyOf":[{"$ref":"#/components/schemas/SourcePlacements"},{"type":"null"}],"description":"What the site sells to brands, from public evidence: what, where that is known from, and its published price or an estimate for its authority. Null where it sells none or was not read yet."},"domain":{"type":"string","title":"Domain"},"group":{"type":"string","enum":["own","rival","review","editorial","community","vendor","other"],"title":"Group"},"ownership":{"type":"string","enum":["own","rival","independent"],"title":"Ownership"},"citations":{"type":"integer","title":"Citations"},"citations_naming_you":{"type":"integer","title":"Citations Naming You","description":"All citations naming the brand, including unread pages. Use read_pages_naming_you for read pages.","deprecated":true},"read_pages_naming_you":{"type":"integer","title":"Read Pages Naming You"},"citation_share_pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Citation Share Pct"},"answers":{"type":"integer","title":"Answers"},"authority":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Authority"},"opportunity_score":{"type":"number","title":"Opportunity Score"},"priority":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Priority","description":"1-based position among worth-pursuing sites under the selected filters; null for sites outside that set. This is a rank, not the internal score."},"priority_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Priority Reason"},"citations_naming_rivals":{"type":"integer","title":"Citations Naming Rivals"},"prompts":{"type":"integer","title":"Prompts"},"engines":{"items":{"type":"string","enum":["perplexity","gemini","openai","google_aio","ai_mode","copilot","claude"]},"type":"array","title":"Engines"},"owner":{"anyOf":[{"type":"string","enum":["third_party","competitor","yours"]},{"type":"null"}],"title":"Owner"},"source_type":{"anyOf":[{"type":"string","enum":["industry_authority","review","regulatory","media","educational","community","consulting","social","vendor","directory","unclassified"]},{"type":"string","const":"corporate"},{"type":"null"}],"title":"Source Type"},"names_you":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Names You"},"answers_share_pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Answers Share Pct"},"change":{"anyOf":[{"$ref":"#/components/schemas/V1SourceChange"},{"type":"null"}]}},"type":"object","required":["verdict","opening","found_via","recommends_you","read_by_searchers","placements","domain","group","ownership","citations","citations_naming_you","read_pages_naming_you","citation_share_pct","answers","authority","opportunity_score","priority","priority_reason","citations_naming_rivals","prompts","engines","owner","source_type","names_you","answers_share_pct","change"],"title":"V1Source"},"V1SourceChange":{"properties":{"direction":{"type":"string","enum":["up","down","flat","new"],"title":"Direction"},"delta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta"},"previous":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Previous"},"current":{"type":"integer","title":"Current"},"label":{"type":"string","title":"Label"}},"type":"object","required":["direction","delta","previous","current","label"],"title":"V1SourceChange"},"V1SourceDetail":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"period":{"$ref":"#/components/schemas/V1Period"},"source":{"$ref":"#/components/schemas/V1SourceFacts"}},"type":"object","required":["meta","period","source"],"title":"V1SourceDetail"},"V1SourceFacts":{"properties":{"verdict":{"type":"string","enum":["recommends_you","names_you","not_named","unread"],"title":"Verdict","description":"Strongest verdict from the pages AI cites on this site.","default":"unread"},"opening":{"type":"boolean","title":"Opening","description":"A pitchable opportunity whose cited pages do not name you.","default":false},"found_via":{"items":{"type":"string","enum":["ai_citation","google_ranking","monitor"]},"type":"array","title":"Found Via"},"recommends_you":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Recommends You"},"read_by_searchers":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Read By Searchers","description":"Estimated monthly readers from tracked keyword volume and ranking click shares, averaged over checks in the period. Never sum across sites. Null when search demand is unavailable."},"placements":{"anyOf":[{"$ref":"#/components/schemas/SourcePlacements"},{"type":"null"}],"description":"What the site sells to brands, from public evidence: what, where that is known from, and its published price or an estimate for its authority. Null where it sells none or was not read yet."},"read_pages":{"type":"integer","title":"Read Pages"},"names_most":{"items":{"$ref":"#/components/schemas/SourceSiteName"},"type":"array","title":"Names Most"},"citation_evidence":{"type":"string","enum":["complete","partial","unavailable"],"title":"Citation Evidence","default":"complete"},"unavailable_scans":{"type":"integer","title":"Unavailable Scans","default":0},"domain":{"type":"string","title":"Domain"},"owner":{"type":"string","enum":["third_party","competitor","yours"],"title":"Owner"},"source_type":{"anyOf":[{"type":"string","enum":["industry_authority","review","regulatory","media","educational","community","consulting","social","vendor","directory","unclassified"]},{"type":"string","const":"corporate"}],"title":"Source Type"},"names_you":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Names You"},"read_pages_naming_you":{"type":"integer","title":"Read Pages Naming You"},"authority":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Authority"},"opportunity_score":{"type":"number","title":"Opportunity Score"},"citations":{"type":"integer","title":"Citations"},"citation_share_pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Citation Share Pct"},"answers":{"type":"integer","title":"Answers"},"answers_share_pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Answers Share Pct"},"change":{"$ref":"#/components/schemas/V1SourceChange"},"reports":{"items":{"$ref":"#/components/schemas/V1PageCitationReport"},"type":"array","title":"Reports"},"pages":{"items":{"$ref":"#/components/schemas/V1SourcePage"},"type":"array","title":"Pages"},"pages_total":{"type":"integer","title":"Pages Total","description":"All pages under the selected filters before paging."},"prompts":{"items":{"$ref":"#/components/schemas/V1PageCitingPrompt"},"type":"array","title":"Prompts"},"prompts_total":{"type":"integer","title":"Prompts Total","description":"All prompts matching this selection before paging."},"prompts_limit":{"type":"integer","title":"Prompts Limit"},"prompts_offset":{"type":"integer","title":"Prompts Offset"},"engines":{"items":{"$ref":"#/components/schemas/V1PageCitingEngine"},"type":"array","title":"Engines"},"muted":{"type":"boolean","title":"Muted"},"partner":{"type":"boolean","title":"Partner"},"possible_partner":{"type":"boolean","title":"Possible Partner"},"pitched":{"type":"boolean","title":"Pitched"},"rates_request":{"anyOf":[{"$ref":"#/components/schemas/ServedInsight"},{"type":"null"}],"description":"Ask for their rates, on an independent site that sells placements: send `rates:<domain>` with kind `rates_request` to file it, and `work` is the rates request already filed. Null on any other site."},"actions":{"items":{"$ref":"#/components/schemas/V1PaneAction"},"type":"array","title":"Actions","description":"One page of the live actions about this source, highest priority first."},"actions_total":{"type":"integer","title":"Actions Total","description":"Every live action about this subject, before the list is cut.","default":0},"actions_limit":{"type":"integer","title":"Actions Limit","default":0},"actions_offset":{"type":"integer","title":"Actions Offset","default":0},"next_step_action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Next Step Action Id","description":"The highest-priority live action that awaits a member and whose verb the reader may press; null when there is none."},"next_step":{"anyOf":[{"$ref":"#/components/schemas/V1PaneAction"},{"type":"null"}],"description":"The action `next_step_action_id` names, in the same shape as `actions`."},"answers_link":{"anyOf":[{"$ref":"#/components/schemas/AnswersLink"},{"type":"null"}]},"introduced_at_run":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Introduced At Run"}},"type":"object","required":["verdict","opening","found_via","recommends_you","read_by_searchers","placements","read_pages","names_most","citation_evidence","unavailable_scans","domain","owner","source_type","names_you","read_pages_naming_you","authority","opportunity_score","citations","citation_share_pct","answers","answers_share_pct","change","reports","pages","pages_total","prompts","prompts_total","prompts_limit","prompts_offset","engines","muted","partner","possible_partner","pitched","rates_request","actions","actions_total","actions_limit","actions_offset","next_step_action_id","next_step","answers_link","introduced_at_run"],"title":"V1SourceFacts"},"V1SourcePage":{"properties":{"language":{"type":"string","title":"Language","default":"unknown"},"document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Id"},"document_key":{"type":"string","title":"Document Key"},"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"domain":{"type":"string","title":"Domain"},"owner":{"type":"string","enum":["third_party","competitor","yours"],"title":"Owner"},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type"},"topic":{"anyOf":[{"$ref":"#/components/schemas/V1SourceTopic"},{"type":"null"}]},"citations":{"type":"integer","title":"Citations"},"prompt_count":{"type":"integer","title":"Prompt Count","description":"Prompts represented by this row under the selected filters."}},"type":"object","required":["language","document_id","document_key","url","title","domain","owner","content_type","topic","citations","prompt_count"],"title":"V1SourcePage"},"V1SourceTopic":{"properties":{"market":{"type":"string","title":"Market","description":"The topic's market: country ISO code, europe or global.","default":"global"},"audience":{"type":"string","title":"Audience","description":"The topic's audience name.","default":"All buyers"},"audience_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Audience Id","description":"Audience UUID; null for All buyers."},"tracked_topic_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tracked Topic Id","description":"Tracked-topic UUID."},"key":{"type":"string","title":"Key"},"topic":{"type":"string","title":"Topic"},"band":{"type":"string","title":"Band","default":"Not measured"}},"type":"object","required":["market","audience","audience_id","tracked_topic_id","key","topic","band"],"title":"V1SourceTopic"},"V1Sources":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"muted_sites":{"type":"integer","title":"Muted Sites","description":"Muted sites under the filters before paging.","default":0},"cited_sites":{"type":"integer","title":"Cited Sites","description":"Distinct cited sites under the filters.","default":0},"sites":{"type":"integer","title":"Sites","description":"All listed sites before paging under the selected mute filter.","default":0},"read_sites":{"type":"integer","title":"Read Sites","description":"Sites with a read cited page.","default":0},"recommending_sites":{"type":"integer","title":"Recommending Sites","description":"Sites with a cited page recommending you.","default":0},"period":{"$ref":"#/components/schemas/V1Period"},"citation_evidence":{"type":"string","enum":["complete","partial","unavailable"],"title":"Citation Evidence","default":"complete"},"unavailable_scans":{"type":"integer","title":"Unavailable Scans","default":0},"sources":{"items":{"$ref":"#/components/schemas/V1Source"},"type":"array","title":"Sources"},"recommending":{"$ref":"#/components/schemas/SourceRecommending"},"channels":{"items":{"$ref":"#/components/schemas/V1Channel"},"type":"array","title":"Channels"},"state":{"anyOf":[{"type":"string","enum":["ready","awaiting_first_scan","unavailable"]},{"type":"null"}],"title":"State"},"card_figures":{"additionalProperties":{"$ref":"#/components/schemas/V1Figure"},"type":"object","title":"Card Figures","description":"Weekly card figures and adjacent-window changes when with_trend=true."},"mix":{"items":{"$ref":"#/components/schemas/SourceMixSegment"},"type":"array","title":"Mix"},"sites_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sites Total","description":"All source sites under the selected filters."},"pages_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages Total","description":"All pages under the selected filters before paging."},"worth_pursuing":{"items":{"$ref":"#/components/schemas/SourceWorthRow"},"type":"array","title":"Worth Pursuing"},"worth_pursuing_total":{"type":"integer","title":"Worth Pursuing Total","description":"All source opportunities under the selected filters before paging.","default":0}},"type":"object","required":["meta","next_cursor","total","limit","offset","muted_sites","cited_sites","sites","read_sites","recommending_sites","period","citation_evidence","unavailable_scans","sources","recommending","channels","state","card_figures","mix","sites_total","pages_total","worth_pursuing","worth_pursuing_total"],"title":"V1Sources","examples":[{"card_figures":{},"channels":[],"citation_evidence":"complete","cited_sites":0,"muted_sites":0,"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"mix":[],"next_cursor":null,"offset":0,"pages_total":null,"period":{"excluded_reports":0,"first_answer_at":null,"last_answer_at":null,"preset":"1w","reports":0},"read_sites":0,"recommending":{"count":0,"naming":0,"total":0},"recommending_sites":0,"sites":0,"sites_total":null,"sources":[],"state":null,"total":0,"unavailable_scans":0,"worth_pursuing":[],"worth_pursuing_total":0}]},"V1StartedSnapshot":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"id":{"type":"string","format":"uuid","title":"Id","description":"The scan's id."},"kind":{"type":"string","enum":["weekly","daily","snapshot","audit"],"title":"Kind","description":"`weekly`, `daily`, `snapshot` (a one-time Snapshot or a brand's first) or `audit`."},"state":{"type":"string","enum":["preparing","running","completed","failed","expired"],"title":"State","description":"`preparing` while the profile drafts or waits for Run, `running`, `completed`, `failed`, or `expired`: a Snapshot whose profile waited 24 hours without a run."},"partial":{"type":"boolean","title":"Partial","description":"A Snapshot delivered before every answer came back, still filling in."},"brand_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Brand Id","description":"Null for a Snapshot no brand holds."},"domain":{"type":"string","title":"Domain","description":"The site the scan measured."},"sells_to":{"type":"string","enum":["businesses","consumers"],"title":"Sells To","description":"Who the scan measured the brand as selling to: `businesses` or `consumers`. Fixed for the scan once it runs."},"ecommerce":{"type":"boolean","title":"Ecommerce","description":"Whether the scan measured the brand as ecommerce, which reads product cards and Google Shopping. Fixed for the scan once it runs."},"started_at":{"type":"string","format":"date-time","title":"Started At","description":"When the scan was started."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When it completed, failed or expired; null until then."},"questions_asked":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Questions Asked","description":"How many questions the scan asks AI engines. A Snapshot asks 20, or 12 to 19 when fewer of its drafted questions passed review. Null before its questions are fixed and on an Audit."},"profile":{"anyOf":[{"$ref":"#/components/schemas/V1SnapshotProfile"},{"type":"null"}],"description":"A preparing Snapshot's profile, to confirm or edit before Run; null while it drafts and once the Snapshot runs."},"run_request":{"anyOf":[{"$ref":"#/components/schemas/V1RunRequest"},{"type":"null"}],"description":"Run pressed before the Snapshot started; null otherwise."},"payer":{"anyOf":[{"$ref":"#/components/schemas/V1SnapshotPayer"},{"type":"null"}],"description":"Who pays for a Snapshot: recorded on Run, charged when it starts. A run that needs action keeps the payer it waits on. Null before Run, after a stop and on other scans."},"share_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Share Id","description":"The report link id once delivered; null on a daily scan and before delivery. Quick shares use /v1/shared/audits/{share_id}; Base and Full remain owner-only."},"report_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Url","description":"A delivered Snapshot's or weekly scan's report page, to give the member; null on an Audit, a daily scan and before delivery."},"progress":{"anyOf":[{"$ref":"#/components/schemas/V1ScanProgress"},{"type":"null"}],"description":"Null on an Audit and once the scan completed or failed."},"audit_progress":{"anyOf":[{"$ref":"#/components/schemas/AuditProgress"},{"type":"null"}],"description":"An Audit's live page and screenshot counts; null on other scans."},"failure_reason":{"anyOf":[{"type":"string","x-extensible-enum":["stuck_no_progress","brief_abandoned","insufficient_engine_signal","cost_cap_exceeded","report_inputs_missing","service_unavailable","other"]},{"type":"null"}],"title":"Failure Reason","description":"Why the scan failed, one of `stuck_no_progress`, `brief_abandoned`, `insufficient_engine_signal`, `cost_cap_exceeded`, `report_inputs_missing`, `service_unavailable` or `other`; null unless the scan failed. New values may be added."},"issued":{"anyOf":[{"$ref":"#/components/schemas/V1ScanFacts"},{"type":"null"}],"description":"What the scan issued once complete; null while it runs, while it is partial, on a daily scan and on an Audit."},"url":{"type":"string","title":"Url","description":"The Snapshot's page, where its member can check the profile, run it and follow it."},"created":{"type":"boolean","title":"Created","description":"False when the start returned your Snapshot of this domain that has not run yet."}},"type":"object","required":["meta","id","kind","state","partial","brand_id","domain","sells_to","ecommerce","started_at","completed_at","questions_asked","profile","run_request","payer","share_id","report_url","progress","audit_progress","failure_reason","issued","url","created"],"title":"V1StartedSnapshot"},"V1StoredMessage":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"conversation_id":{"type":"string","format":"uuid","title":"Conversation Id"},"seq":{"type":"integer","title":"Seq"},"parts":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Parts"},"kind":{"type":"string","enum":["person","member","event"],"title":"Kind"},"author":{"type":"string","title":"Author"},"reply_to":{"anyOf":[{"$ref":"#/components/schemas/V1ConversationQuote"},{"type":"null"}]},"suggestions":{"items":{"$ref":"#/components/schemas/V1ConversationProposal"},"type":"array","title":"Suggestions"},"answer_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Answer Status"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","conversation_id","seq","parts","kind","author","reply_to","suggestions","answer_status","created_at"],"title":"V1StoredMessage"},"V1Topic":{"properties":{"measurement_status":{"type":"string","enum":["new","measured"],"title":"Measurement Status","description":"New until a subscription weekly report scores it, then measured. Independent of tracking state.","default":"new"},"first_answers_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Answers At","description":"The first answered time, or the estimate while its prompt read is pending. Null when no estimate is available."},"first_score_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"First Score On","description":"The next weekly report's date for the market. Null before the brand has a weekly schedule."},"id":{"type":"string","title":"Id","description":"The tracked-topic UUID, or `s:{id}` for a suggestion. Use it in topics/{id}."},"topic":{"type":"string","title":"Topic"},"suggestion_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suggestion Id","description":"The suggestion to track; null for a tracked topic."},"tracked_topic_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Tracked Topic Id","description":"The tracked-topic identity, fixed to one market and audience."},"market":{"type":"string","title":"Market","description":"The topic's market: country ISO code, europe or global.","default":"global"},"audience":{"type":"string","title":"Audience","description":"The audience's name, or All buyers.","default":"All buyers"},"audience_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Audience Id","description":"Audience UUID; null for All buyers."},"state":{"type":"string","enum":["tracked","suggested","archived"],"title":"State"},"archived_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Archived At","description":"When the topic was archived; null unless archived."},"need":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Need","description":"The buyer need the topic is for, in a sentence."},"scores":{"anyOf":[{"$ref":"#/components/schemas/TopicScores"},{"type":"null"}],"description":"The topic's Heralded Score on `all`, `ai` and `search`, each with its band, change, Mentioned and Recommended; null on a suggested topic. A side with no reading has a null value."},"leader":{"anyOf":[{"$ref":"#/components/schemas/V1TopicLeader"},{"type":"null"}],"description":"The brand that clearly leads on AI; null without a clear leader."},"prompts_count":{"type":"integer","title":"Prompts Count","description":"Prompts tracked in this topic."},"prompts_filtered":{"type":"integer","title":"Prompts Filtered","default":0},"band":{"type":"string","enum":["Invisible","Under-visible","Emerging","Strong","Leader","Not measured"],"title":"Band","default":"Not measured"},"leader_state":{"type":"string","enum":["measured","no_clear_leader","not_measured"],"title":"Leader State","description":"`measured`: one brand clearly leads and leader names it. `no_clear_leader`: your Heralded Score is measured but no brand clearly leads. `not_measured`: your Heralded Score is not measured.","default":"not_measured"},"cited_share":{"$ref":"#/components/schemas/CitedShare"},"unanswered_questions":{"type":"integer","title":"Unanswered Questions","default":0},"keywords_count":{"type":"integer","title":"Keywords Count","description":"Keywords tracked in this topic."},"why_labels":{"items":{"type":"string"},"type":"array","title":"Why Labels","description":"Why a suggested topic is suggested."},"best_to_track":{"type":"boolean","title":"Best To Track"},"demand":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Demand"},"demand_countries":{"items":{"$ref":"#/components/schemas/TopicCountryDemand"},"type":"array","title":"Demand Countries","description":"Per-country monthly keyword totals for tracked topics; empty on suggestions."},"volume_partial":{"type":"boolean","title":"Volume Partial","description":"True when any tracked keyword or country has unknown volume.","default":false},"demand_measured":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Demand Measured","description":"A suggested topic only."},"evidence":{"anyOf":[{"items":{"$ref":"#/components/schemas/V1TopicEvidence"},"type":"array"},{"type":"null"}],"title":"Evidence","description":"What led to a suggested topic: its searches and questions, with counts, then the questions members added to it. Null on a tracked topic."},"coverage":{"anyOf":[{"type":"string","enum":["covered","weak","missing","unchecked","uncovered","unknown"]},{"type":"null"}],"title":"Coverage","description":"A suggested topic only: whether a page of the brand's answers it."},"actions":{"anyOf":[{"items":{"$ref":"#/components/schemas/V1TopicNeedAction"},"type":"array"},{"type":"null"}],"title":"Actions","description":"A suggested topic only."},"adds":{"anyOf":[{"$ref":"#/components/schemas/V1TopicAdds"},{"type":"null"}],"description":"What tracking a suggested topic adds. Null until it is tracked: its prompts and keywords are drafted then."}},"type":"object","required":["measurement_status","first_answers_at","first_score_on","id","topic","suggestion_id","tracked_topic_id","market","audience","audience_id","state","archived_at","need","scores","leader","prompts_count","prompts_filtered","band","leader_state","cited_share","unanswered_questions","keywords_count","why_labels","best_to_track","demand","demand_countries","volume_partial","demand_measured","evidence","coverage","actions","adds"],"title":"V1Topic"},"V1TopicAdds":{"properties":{"prompts":{"type":"integer","title":"Prompts"},"keywords":{"type":"integer","title":"Keywords"}},"type":"object","required":["prompts","keywords"],"title":"V1TopicAdds"},"V1TopicAiCount":{"properties":{"numerator":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Numerator","description":"The answers that count; null where not measured."},"denominator":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Denominator","description":"The answers it is counted over; null where not measured."},"answers":{"type":"integer","title":"Answers","description":"All AI answers the figure reads."}},"type":"object","required":["numerator","denominator","answers"],"title":"V1TopicAiCount"},"V1TopicAiCounts":{"properties":{"mentioned":{"$ref":"#/components/schemas/V1TopicAiCount","description":"The answers that mention you."},"recommended":{"$ref":"#/components/schemas/V1TopicAiCount","description":"The answers that recommend you."}},"type":"object","required":["mentioned","recommended"],"title":"V1TopicAiCounts"},"V1TopicBandOption":{"properties":{"value":{"type":"string","enum":["Invisible","Under-visible","Emerging","Strong","Leader","Not measured"],"title":"Value"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["value","count"],"title":"V1TopicBandOption"},"V1TopicBrand":{"properties":{"name":{"type":"string","title":"Name","description":"The brand's name."},"is_you":{"type":"boolean","title":"Is You","description":"Whether this is your own brand rather than a competitor."},"scores":{"$ref":"#/components/schemas/TopicScores"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"The brand's website domain; null where Heralded has none."},"mentioned_change":{"anyOf":[{"$ref":"#/components/schemas/FigureChange"},{"type":"null"}],"description":"How its Mentioned moved on `side`."},"recommended_change":{"anyOf":[{"$ref":"#/components/schemas/FigureChange"},{"type":"null"}],"description":"How its Recommended moved on `side`."},"rank":{"type":"integer","title":"Rank","description":"The brand's 1-based place among the topic's brands on `side`: by score on `ai` and `all`, by Mentioned on `search`."}},"type":"object","required":["name","is_you","scores","domain","mentioned_change","recommended_change","rank"],"title":"V1TopicBrand"},"V1TopicCitedPage":{"properties":{"source_type":{"anyOf":[{"type":"string","enum":["industry_authority","review","regulatory","media","educational","community","consulting","social","vendor","directory","unclassified"]},{"type":"string","const":"corporate"}],"title":"Source Type","description":"The site's type, using the Sources vocabulary."},"owner":{"type":"string","enum":["third_party","competitor","yours"],"title":"Owner","description":"Whether the site is yours, a competitor's or third-party."},"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"domain":{"type":"string","title":"Domain"},"group":{"type":"string","title":"Group"},"cited":{"type":"integer","title":"Cited","description":"Times AI answers cited it in the period. A floor unless citation_evidence is complete."},"you":{"anyOf":[{"type":"string","enum":["yours","names_you","doesnt_name_you"]},{"type":"null"}],"title":"You","description":"Whether it is yours, names you or does not; null where no answer read it."}},"type":"object","required":["source_type","owner","url","title","domain","group","cited","you"],"title":"V1TopicCitedPage"},"V1TopicDetail":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"measurement_status":{"type":"string","enum":["new","measured"],"title":"Measurement Status","description":"New until a subscription weekly report scores it, then measured. Independent of tracking state.","default":"new"},"first_answers_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Answers At","description":"The first answered time, or the estimate while its prompt read is pending. Null when no estimate is available."},"first_score_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"First Score On","description":"The next weekly report's date for the market. Null before the brand has a weekly schedule."},"id":{"type":"string","title":"Id","description":"The tracked-topic UUID, or `s:{id}` for a suggestion. Use it in topics/{id}."},"topic":{"type":"string","title":"Topic"},"suggestion_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suggestion Id","description":"The suggestion to track; null for a tracked topic."},"tracked_topic_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Tracked Topic Id","description":"The tracked-topic identity, fixed to one market and audience."},"market":{"type":"string","title":"Market","description":"The topic's market: country ISO code, europe or global.","default":"global"},"audience":{"type":"string","title":"Audience","description":"The audience's name, or All buyers.","default":"All buyers"},"audience_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Audience Id","description":"Audience UUID; null for All buyers."},"state":{"type":"string","enum":["tracked","suggested","archived"],"title":"State"},"archived_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Archived At","description":"When the topic was archived; null unless archived."},"need":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Need","description":"The buyer need the topic is for, in a sentence."},"scores":{"anyOf":[{"$ref":"#/components/schemas/TopicScores"},{"type":"null"}],"description":"The topic's Heralded Score on `all`, `ai` and `search`, each with its band, change, Mentioned and Recommended; null on a suggested topic. A side with no reading has a null value."},"leader":{"anyOf":[{"$ref":"#/components/schemas/V1TopicLeader"},{"type":"null"}],"description":"The brand that clearly leads on AI; null without a clear leader."},"prompts_count":{"type":"integer","title":"Prompts Count","description":"Prompts tracked in this topic."},"prompts_filtered":{"type":"integer","title":"Prompts Filtered","default":0},"band":{"type":"string","enum":["Invisible","Under-visible","Emerging","Strong","Leader","Not measured"],"title":"Band","default":"Not measured"},"leader_state":{"type":"string","enum":["measured","no_clear_leader","not_measured"],"title":"Leader State","description":"`measured`: one brand clearly leads and leader names it. `no_clear_leader`: your Heralded Score is measured but no brand clearly leads. `not_measured`: your Heralded Score is not measured.","default":"not_measured"},"cited_share":{"$ref":"#/components/schemas/CitedShare"},"unanswered_questions":{"type":"integer","title":"Unanswered Questions","default":0},"keywords_count":{"type":"integer","title":"Keywords Count","description":"Keywords tracked in this topic."},"why_labels":{"items":{"type":"string"},"type":"array","title":"Why Labels","description":"Why a suggested topic is suggested."},"best_to_track":{"type":"boolean","title":"Best To Track"},"demand":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Demand"},"demand_countries":{"items":{"$ref":"#/components/schemas/TopicCountryDemand"},"type":"array","title":"Demand Countries","description":"Per-country monthly keyword totals for tracked topics; empty on suggestions."},"volume_partial":{"type":"boolean","title":"Volume Partial","description":"True when any tracked keyword or country has unknown volume.","default":false},"demand_measured":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Demand Measured","description":"A suggested topic only."},"evidence":{"anyOf":[{"items":{"$ref":"#/components/schemas/V1TopicEvidence"},"type":"array"},{"type":"null"}],"title":"Evidence","description":"What led to a suggested topic: its searches and questions, with counts, then the questions members added to it. Null on a tracked topic."},"coverage":{"anyOf":[{"type":"string","enum":["covered","weak","missing","unchecked","uncovered","unknown"]},{"type":"null"}],"title":"Coverage","description":"A suggested topic only: whether a page of the brand's answers it."},"actions":{"anyOf":[{"items":{"$ref":"#/components/schemas/V1TopicNeedAction"},"type":"array"},{"type":"null"}],"title":"Actions","description":"A suggested topic only."},"adds":{"anyOf":[{"$ref":"#/components/schemas/V1TopicAdds"},{"type":"null"}],"description":"What tracking a suggested topic adds. Null until it is tracked: its prompts and keywords are drafted then."},"engines":{"items":{"type":"string"},"type":"array","title":"Engines","description":"The engines selected for this topic."},"focus_selection":{"anyOf":[{"$ref":"#/components/schemas/Focus"},{"type":"null"}],"description":"The brand’s current focus selection and capacity."},"pane_figures":{"anyOf":[{"$ref":"#/components/schemas/V1SideFigures"},{"type":"null"}],"description":"The selected side’s figure values, comparisons and small weekly trends."},"own_pages_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Own Pages Total","description":"All own pages serving this topic before paging."},"answered_questions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Answered Questions","description":"Questions the topic’s own pages answer under the selection; unknown questions are excluded."},"own_pages":{"items":{"$ref":"#/components/schemas/TopicOwnPage"},"type":"array","title":"Own Pages"},"coverage_questions":{"items":{"$ref":"#/components/schemas/TopicQuestionResult"},"type":"array","title":"Coverage Questions"},"ai_score_series":{"items":{"$ref":"#/components/schemas/FigurePoint"},"type":"array","title":"Heralded Score series"},"live_actions":{"items":{"$ref":"#/components/schemas/V1Action"},"type":"array","title":"Live Actions","description":"The live actions about this topic, highest priority first."},"actions_total":{"type":"integer","title":"Actions Total","description":"Every live action about this subject, before the list is cut.","default":0},"next_step_action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Next Step Action Id","description":"The highest-priority live action that awaits a member and whose verb the reader may press; null when there is none."},"next_step":{"anyOf":[{"$ref":"#/components/schemas/V1Action"},{"type":"null"}],"description":"The action `next_step_action_id` names, in the same shape as `actions`."},"english_name_suggestion":{"anyOf":[{"$ref":"#/components/schemas/EnglishTopicName"},{"type":"null"}],"description":"The cached English name offered for member acceptance."},"search_term":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search Term","description":"The topic's retained local search term."},"answers_link":{"anyOf":[{"$ref":"#/components/schemas/AnswersLink"},{"type":"null"}]},"period":{"$ref":"#/components/schemas/V1Period"},"sides_available":{"items":{"type":"string","enum":["ai","search"]},"type":"array","title":"Sides Available","description":"The sides the period's reports observed: `ai`, and `search` once a report checked keywords. A read of reports without search observations states `[\"ai\"]`, and `all` is then the AI side."},"citation_evidence":{"type":"string","enum":["complete","partial","unavailable"],"title":"Citation Evidence","default":"complete"},"unavailable_scans":{"type":"integer","title":"Unavailable Scans","default":0},"prompts":{"items":{"$ref":"#/components/schemas/V1TopicPrompt"},"type":"array","title":"Prompts"},"prompts_total":{"type":"integer","title":"Prompts Total","description":"All prompts matching this selection before paging."},"pages":{"items":{"$ref":"#/components/schemas/V1TopicCitedPage"},"type":"array","title":"Pages","description":"The pages its prompts cite most. Google ranks join them with the search side."},"keywords":{"items":{"$ref":"#/components/schemas/V1TopicKeyword"},"type":"array","title":"Keywords","description":"Its active and paused keywords."},"keyword_research":{"items":{"$ref":"#/components/schemas/V1TopicKeywordResearch"},"type":"array","title":"Keyword Research","description":"Whether keyword research found none or was unavailable for this topic."},"winners":{"items":{"$ref":"#/components/schemas/TopicStanding"},"type":"array","title":"Winners","description":"The brand and its rivals, best score on the topic on `side` first; at most five."},"by_engine":{"anyOf":[{"items":{"$ref":"#/components/schemas/V1ScoreRow"},"type":"array"},{"type":"null"}],"title":"By Engine","description":"Only with `with_pane`. The topic's figures on each AI engine that answered in the period, in the engines' order: the rows `scores` serves with `group_by=engine` and `topic`, under the request's filters except `engine`."},"paused_engines":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Paused Engines","description":"Only with `with_pane`. The engines paused for the latest report in the period, in registry order. Like `by_engine`, this list ignores the `engine` filter."},"ai_counts":{"anyOf":[{"$ref":"#/components/schemas/V1TopicAiCounts"},{"type":"null"}],"description":"Only with `with_pane`. How many AI answers mention you and how many recommend you, each over the answers it is counted over: the `numerator`, `denominator` and `answers` that `figures.mentioned` and `figures.recommended` carry for the same period and filters."},"search_trend":{"anyOf":[{"items":{"$ref":"#/components/schemas/V1TrendPoint"},"type":"array"},{"type":"null"}],"title":"Search Trend","description":"Only with `with_pane`. Mentioned on the Search side per weekly report, as `scores` trends it. Empty when no report checked the topic's keywords."},"keywords_top10":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Keywords Top10","description":"Only with `with_pane`. How many of its active and paused keywords have one of your pages in the ten results of their latest check. `keywords_count` is the total."},"brands":{"anyOf":[{"items":{"$ref":"#/components/schemas/V1TopicBrand"},"type":"array"},{"type":"null"}],"title":"Brands","description":"Only with `with_pane`. The first five of the brand and its rivals, best on `side` first, by Mentioned on `search`. When you rank lower than fifth, you take the fifth place."},"brands_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Brands Total","description":"Only with `with_pane`. All brands ranked on the topic, you included."},"pages_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages Total","description":"Only with `with_pane`. All pages its prompts cite, before `pages` cuts them."}},"type":"object","required":["meta","measurement_status","first_answers_at","first_score_on","id","topic","suggestion_id","tracked_topic_id","market","audience","audience_id","state","archived_at","need","scores","leader","prompts_count","prompts_filtered","band","leader_state","cited_share","unanswered_questions","keywords_count","why_labels","best_to_track","demand","demand_countries","volume_partial","demand_measured","evidence","coverage","actions","adds","engines","own_pages","coverage_questions","ai_score_series","live_actions","actions_total","next_step_action_id","next_step","english_name_suggestion","search_term","answers_link","period","sides_available","citation_evidence","unavailable_scans","prompts","prompts_total","pages","keywords","keyword_research","winners"],"title":"V1TopicDetail"},"V1TopicEvidence":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Id","description":"Set on a question a member added, which the app edits and deletes by this id; null on every other kind."},"kind":{"type":"string","title":"Kind","description":"Where it was found: `search_console`, `people_also_ask`, `reddit`, `stack_exchange`, `labs_demand` (Google keyword demand) or `member_question` (a question a member added, seen only in the workspace). `engine_searches` are what AI engines searched while answering; they are leads, not buyer evidence. Other kinds are Heralded's own inputs."},"text":{"type":"string","title":"Text","description":"The phrasing as found."},"count":{"type":"integer","title":"Count"},"engines":{"items":{"type":"string"},"type":"array","title":"Engines","description":"AI engines whose background searches produced this evidence."},"impressions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Impressions","description":"Search Console impressions for the query; null otherwise."},"searches_mo":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Searches Mo","description":"Monthly Google searches for the phrase in the market, where Heralded already holds the figure; null otherwise."}},"type":"object","required":["id","kind","text","count","engines","impressions","searches_mo"],"title":"V1TopicEvidence","description":"One piece of stored evidence. Reading it never buys research."},"V1TopicKeyword":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The keyword's stable id."},"text":{"type":"string","title":"Text"},"status":{"type":"string","enum":["active","paused"],"title":"Status"},"source":{"type":"string","enum":["researched","member"],"title":"Source","description":"Whether this keyword came from research or a member."},"replaced_by_next_add":{"type":"boolean","title":"Replaced By Next Add","description":"Whether a member's next add in this topic and country would replace this keyword at the cap."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"language":{"type":"string","title":"Language","default":"en"},"master_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Master Text"},"searches_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Searches Total","description":"All measured searches represented by this keyword."},"volume_partial":{"type":"boolean","title":"Volume Partial","default":false},"countries":{"items":{"$ref":"#/components/schemas/KeywordCountry"},"type":"array","title":"Countries"},"searches_mo":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Searches Mo"},"best_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Rank"}},"type":"object","required":["id","text","status","source","replaced_by_next_add","country","language","master_text","searches_total","volume_partial","countries","searches_mo","best_rank"],"title":"V1TopicKeyword"},"V1TopicKeywordResearch":{"properties":{"unavailable":{"type":"boolean","title":"Unavailable","description":"Keyword research was unavailable for the topic's market."},"found_none":{"type":"boolean","title":"Found None","description":"Research ran but found no keywords for this topic."}},"type":"object","required":["unavailable","found_none"],"title":"V1TopicKeywordResearch"},"V1TopicLeader":{"properties":{"name":{"type":"string","title":"Name"},"is_you":{"type":"boolean","title":"Is You"}},"type":"object","required":["name","is_you"],"title":"V1TopicLeader"},"V1TopicNeedAction":{"properties":{"kind":{"type":"string","enum":["track","swap_for","write"],"title":"Kind"},"tracked_topic_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Tracked Topic Id","description":"The tracked topic a swap_for action replaces."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"type":"object","required":["kind","tracked_topic_id","name"],"title":"V1TopicNeedAction"},"V1TopicPrompt":{"properties":{"measurement_status":{"type":"string","enum":["new","measured"],"title":"Measurement Status","description":"New until a subscription weekly report scores it, then measured. Independent of tracking state.","default":"new"},"first_answers_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Answers At","description":"The first answered time, or the estimate while its prompt read is pending. Null when no estimate is available."},"first_score_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"First Score On","description":"The next weekly report's date for the market. Null before the brand has a weekly schedule."},"prompt_id":{"type":"string","format":"uuid","title":"Prompt Id"},"text":{"type":"string","title":"Text"},"score":{"anyOf":[{"$ref":"#/components/schemas/ScoreMark"},{"type":"null"}]},"trend":{"anyOf":[{"$ref":"#/components/schemas/PromptTrend"},{"type":"null"}]},"engines":{"items":{"$ref":"#/components/schemas/V1TopicPromptEngine"},"type":"array","title":"Engines"}},"type":"object","required":["measurement_status","first_answers_at","first_score_on","prompt_id","text","score","trend","engines"],"title":"V1TopicPrompt"},"V1TopicPromptEngine":{"properties":{"engine":{"type":"string","title":"Engine"},"mentioned":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentioned"},"recommended":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Recommended"}},"type":"object","required":["engine","mentioned","recommended"],"title":"V1TopicPromptEngine"},"V1Topics":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"period":{"$ref":"#/components/schemas/V1Period"},"sides_available":{"items":{"type":"string","enum":["ai","search"]},"type":"array","title":"Sides Available","description":"The sides the period's reports observed: `ai`, and `search` once a report checked keywords. A read of reports without search observations states `[\"ai\"]`, and `all` is then the AI side."},"state":{"type":"string","enum":["ready","awaiting_first_scan","not_measured"],"title":"State"},"topics":{"items":{"$ref":"#/components/schemas/V1Topic"},"type":"array","title":"Topics"},"card_figures":{"additionalProperties":{"$ref":"#/components/schemas/V1Figure"},"type":"object","title":"Card Figures","description":"Weekly card figures and adjacent-window changes when with_trend=true."},"search_connected":{"type":"boolean","title":"Search Connected"},"ai_visits_connected":{"type":"boolean","title":"Ai Visits Connected"},"tracked_total":{"type":"integer","title":"Tracked Total","description":"Topics tracked in a live market and audience.","default":0},"archived_total":{"type":"integer","title":"Archived Total","description":"Archived topics.","default":0},"leading":{"type":"integer","title":"Leading","default":0},"competing":{"type":"integer","title":"Competing","default":0},"cited_share":{"$ref":"#/components/schemas/CitedShare"},"unanswered_questions":{"type":"integer","title":"Unanswered Questions","default":0},"bands":{"items":{"$ref":"#/components/schemas/V1TopicBandOption"},"type":"array","title":"Bands"}},"type":"object","required":["meta","next_cursor","total","limit","offset","period","sides_available","state","topics","card_figures","search_connected","ai_visits_connected","tracked_total","archived_total","leading","competing","cited_share","unanswered_questions","bands"],"title":"V1Topics","examples":[{"ai_visits_connected":false,"archived_total":0,"bands":[],"card_figures":{},"cited_share":{"answers":0,"citing_answers":null,"state":"measured","value":null},"competing":0,"leading":0,"limit":20,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}},"next_cursor":null,"offset":0,"period":{"excluded_reports":0,"first_answer_at":null,"last_answer_at":null,"preset":"1w","reports":0},"search_connected":false,"sides_available":[],"state":"ready","topics":[],"total":0,"tracked_total":0,"unanswered_questions":0}]},"V1TrendPoint":{"properties":{"at":{"type":"string","format":"date-time","title":"At"},"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value"},"low":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Low"},"high":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"High"},"answers":{"type":"integer","title":"Answers"},"state":{"type":"string","title":"State","x-extensible-enum":["measured","too_few_answers","calibrating","first_report","not_comparable","not_measured","pending","not_scored"]},"break":{"anyOf":[{"$ref":"#/components/schemas/TrendBreak"},{"type":"null"}]}},"type":"object","required":["at","value","low","high","answers","state","break"],"title":"V1TrendPoint"},"V1Usage":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"usage":{"$ref":"#/components/schemas/WorkspaceUsage"}},"type":"object","required":["meta","organization_id","usage"],"title":"V1Usage"},"V1VerifiedAction":{"properties":{"first_citation":{"anyOf":[{"$ref":"#/components/schemas/FirstCitation"},{"type":"null"}],"description":"First qualifying citation of the delivered page; null while uncited."},"citation_count":{"type":"integer","title":"Citation Count","description":"Distinct engine and stable prompt pairs citing the delivered page within its measurement window.","default":0},"action_id":{"type":"string","format":"uuid","title":"Action Id"},"title":{"type":"string","title":"Title"},"credited_pts":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Credited Pts"},"before":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"string"},{"type":"null"}],"title":"Before"},"after":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"string"},{"type":"null"}],"title":"After"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"},"happened":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Happened","description":"What the work did, in a line."},"gain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gain","description":"The gain verification credited, in a line."}},"type":"object","required":["first_citation","citation_count","action_id","title","credited_pts","before","after","completed_at","happened","gain"],"title":"V1VerifiedAction"},"V1VerifiedActions":{"properties":{"rows":{"items":{"$ref":"#/components/schemas/V1VerifiedAction"},"type":"array","title":"Rows","description":"The newest three."},"total":{"type":"integer","title":"Total"}},"type":"object","required":["rows","total"],"title":"V1VerifiedActions","description":"Delivered work with a verified gain or a cited page, newest result first."},"V1VisitCoverage":{"properties":{"start":{"type":"string","format":"date","title":"Start"},"end":{"type":"string","format":"date","title":"End"}},"type":"object","required":["start","end"],"title":"V1VisitCoverage"},"V1VoiceShare":{"properties":{"name":{"type":"string","title":"Name"},"is_you":{"type":"boolean","title":"Is You"},"numerator":{"type":"integer","title":"Numerator"},"denominator":{"type":"integer","title":"Denominator"},"pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct"}},"type":"object","required":["name","is_you","numerator","denominator","pct"],"title":"V1VoiceShare"},"V1Website":{"properties":{"state":{"type":"string","enum":["complete","pending","unavailable"],"title":"State","description":"complete, or pending or unavailable, which carry no figures."},"score":{"anyOf":[{"$ref":"#/components/schemas/V1WebsiteScore"},{"type":"null"}]},"groups":{"items":{"$ref":"#/components/schemas/V1WebsiteGroup"},"type":"array","title":"Groups"},"areas":{"items":{"$ref":"#/components/schemas/V1WebsiteArea"},"type":"array","title":"Areas"},"findings":{"items":{"$ref":"#/components/schemas/V1WebsiteFinding"},"type":"array","title":"Findings"},"fix_first":{"items":{"type":"string"},"type":"array","title":"Fix First","description":"Finding ids, the fix to make first leading."},"pages_with_findings":{"anyOf":[{"$ref":"#/components/schemas/V1PagesWithFindings"},{"type":"null"}]},"coverage":{"anyOf":[{"$ref":"#/components/schemas/V1WebsiteCoverage"},{"type":"null"}]},"versions":{"anyOf":[{"$ref":"#/components/schemas/V1WebsiteVersions"},{"type":"null"}]},"changes":{"anyOf":[{"$ref":"#/components/schemas/V1WebsiteChanges"},{"type":"null"}],"description":"Since the brand's previous weekly read; null on its first and on a scan."},"measured_more_deeply":{"type":"boolean","title":"Measured More Deeply","description":"The first weekly score after a Base or Full audit, which read the site more deeply."}},"type":"object","required":["state","score","groups","areas","findings","fix_first","pages_with_findings","coverage","versions","changes","measured_more_deeply"],"title":"V1Website"},"V1WebsiteAction":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Open it with get_action or /v1/actions/{id}."},"state":{"type":"string","title":"State"},"status":{"type":"string","title":"Status","description":"The customer-facing stage from the work projection."},"assignee":{"anyOf":[{"$ref":"#/components/schemas/AssigneeResponse"},{"type":"null"}]}},"type":"object","required":["id","state","status","assignee"],"title":"V1WebsiteAction"},"V1WebsiteArea":{"properties":{"area":{"type":"string","enum":["positioning","content","proof","conversion","design","seo","ai_visibility","technical"],"title":"Area"},"group":{"type":"string","enum":["message","experience","reach"],"title":"Group"},"score":{"$ref":"#/components/schemas/V1WebsiteScore"},"findings":{"items":{"type":"string"},"type":"array","title":"Findings","description":"The ids of its findings that hold something back, most points first."}},"type":"object","required":["area","group","score","findings"],"title":"V1WebsiteArea"},"V1WebsiteBands":{"properties":{"good":{"type":"integer","title":"Good","description":"A score at or above it is good."},"needs_work":{"type":"integer","title":"Needs Work","description":"A score at or above it, below good, needs work."}},"type":"object","required":["good","needs_work"],"title":"V1WebsiteBands"},"V1WebsiteChanges":{"properties":{"new_pages":{"items":{"type":"string"},"type":"array","title":"New Pages"},"changed_pages":{"items":{"type":"string"},"type":"array","title":"Changed Pages"},"rules_changed":{"type":"boolean","title":"Rules Changed","description":"The rules changed since the last read, which claims no fixed or new finding."},"fixed_findings":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Fixed Findings","description":"Null when rules_changed."},"new_findings":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"New Findings","description":"Null when rules_changed."}},"type":"object","required":["new_pages","changed_pages","rules_changed","fixed_findings","new_findings"],"title":"V1WebsiteChanges"},"V1WebsiteCoverage":{"properties":{"found":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Found","description":"Addresses the crawl found, redirects and other domains included; pages counts the pages on the site."},"read":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Read","description":"Addresses the crawl read."},"truncated":{"type":"boolean","title":"Truncated","description":"A budget, deadline or sample cut the read short.","default":false},"languages":{"items":{"$ref":"#/components/schemas/V1WebsiteLanguage"},"type":"array","title":"Languages"},"pages":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages","description":"Pages on the site: every page the run's site map draws, one per address on the brand's domain, in every language. Null where the run froze no site map."},"pages_read":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages Read","description":"Of pages, those the run read; null with pages."},"pages_ai_readable":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages Ai Readable","description":"Of pages_read, those that load and that AI engines can read: robots.txt lets AI search crawlers in, no bot challenge answers and the text needs no JavaScript; null with pages."}},"type":"object","required":["found","read","truncated","languages","pages","pages_read","pages_ai_readable"],"title":"V1WebsiteCoverage"},"V1WebsiteFinding":{"properties":{"id":{"type":"string","title":"Id","description":"The finding's stable identifier."},"area":{"type":"string","enum":["positioning","content","proof","conversion","design","seo","ai_visibility","technical"],"title":"Area","description":"The Website area the finding belongs to."},"group":{"type":"string","enum":["message","experience","reach"],"title":"Group","description":"The Website group the area belongs to."},"state":{"type":"string","enum":["measured","unmeasured","not_applicable"],"title":"State","description":"measured, unmeasured (with a reason) or not_applicable. Only a measured finding enters a score, and not measured is never zero."},"reason":{"anyOf":[{"type":"string","x-extensible-enum":["no_brief","not_in_quick","not_read","pending","provider_unavailable","truncated"]},{"type":"null"}],"title":"Reason","description":"Why it was not measured; null when measured. not_in_quick is a check a Quick audit leaves to Base. New values may be added."},"severity":{"type":"string","enum":["issue","improve","info"],"title":"Severity","description":"issue, improve, or info: measured and shown, outside every score."},"share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Share","description":"How much of what it reads holds the finding, 0 to 1; null unless measured."},"passed":{"type":"boolean","title":"Passed","description":"Whether the measured check passed; false when it failed or was not measured."},"detail":{"type":"string","title":"Detail","description":"What was found; on an unmeasured finding, why it could not be measured."},"pages":{"anyOf":[{"$ref":"#/components/schemas/V1WebsiteFindingPages"},{"type":"null"}],"description":"The pages it names; null for a finding about the whole site."},"sampled":{"type":"boolean","title":"Sampled","description":"Counted from a sample of a collection or archive."},"points_off_area":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Points Off Area","description":"What it takes off its area's score."},"fix_steps":{"items":{"type":"string"},"type":"array","title":"Fix Steps","description":"Steps that address this finding."},"action":{"anyOf":[{"$ref":"#/components/schemas/V1WebsiteAction"},{"type":"null"}],"description":"The newest open work filed for it; null where none is, always on info."},"held_back":{"type":"boolean","title":"Held Back","description":"A suggestion covering it waits beyond the plan's open suggestions, so Actions does not show it yet; `action` is null then.","default":false},"can_add":{"type":"boolean","title":"Can Add","description":"A member can add it to Actions as their own request: the brand's latest weekly read holds it, no shown action covers it, and either a held-back suggestion covers it or nothing started or settled does. Always false on info.","default":false},"insight":{"anyOf":[{"$ref":"#/components/schemas/ServedInsight"},{"type":"null"}],"description":"The work that fits it and the work filed from it; null on info, and on a page whose finding is another page's work."},"points_off_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Points Off Score","description":"What it takes off the Website score; null unless measured, and on info."},"finding_pages_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Finding Pages Total","description":"All pages named by this finding before paging.","readOnly":true}},"type":"object","required":["id","area","group","state","reason","severity","share","passed","detail","pages","sampled","points_off_area","fix_steps","action","held_back","can_add","insight","points_off_score","finding_pages_total"],"title":"V1WebsiteFinding"},"V1WebsiteFindingPages":{"properties":{"count":{"type":"integer","title":"Count","description":"Every page the finding names."},"urls":{"items":{"type":"string"},"type":"array","title":"Urls","description":"Up to finding_pages_limit of them, from offset."},"titles":{"items":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"array","title":"Titles","description":"Each of `urls`' titles as the run read them, in the same order; null where the run's site graph holds no title for the page."},"notes":{"items":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"array","title":"Notes","description":"Each URL's finding note in the same order as urls; null where the stored assessment has none."},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["count","urls","titles","notes","offset"],"title":"V1WebsiteFindingPages"},"V1WebsiteGroup":{"properties":{"group":{"type":"string","enum":["message","experience","reach"],"title":"Group"},"score":{"$ref":"#/components/schemas/V1WebsiteScore"},"areas":{"items":{"type":"string","enum":["positioning","content","proof","conversion","design","seo","ai_visibility","technical"]},"type":"array","title":"Areas"}},"type":"object","required":["group","score","areas"],"title":"V1WebsiteGroup"},"V1WebsiteLanguage":{"properties":{"code":{"type":"string","title":"Code"},"root":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Root"},"found":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Found","description":"Pages found in the language."},"read":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Read","description":"Pages read in the language; null on reads that kept no count."}},"type":"object","required":["code","root","found","read"],"title":"V1WebsiteLanguage"},"V1WebsiteScore":{"properties":{"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value","description":"0 to 100; null where nothing it averages was measured."},"band":{"anyOf":[{"type":"string","enum":["good","needs_work","poor"]},{"type":"null"}],"title":"Band","description":"good, needs_work or poor, by versions.bands."}},"type":"object","required":["value","band"],"title":"V1WebsiteScore"},"V1WebsiteSeriesPoint":{"properties":{"scan_id":{"type":"string","format":"uuid","title":"Scan Id"},"run_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Run Number"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"},"score":{"$ref":"#/components/schemas/V1WebsiteScore"},"groups":{"items":{"$ref":"#/components/schemas/V1WebsiteGroup"},"type":"array","title":"Groups"},"pages_with_findings":{"$ref":"#/components/schemas/V1PagesWithFindings"},"break_before":{"type":"boolean","title":"Break Before","description":"The rules or policy differ from the previous point's: the line breaks."},"measured_more_deeply":{"type":"boolean","title":"Measured More Deeply"}},"type":"object","required":["scan_id","run_number","completed_at","score","groups","pages_with_findings","break_before","measured_more_deeply"],"title":"V1WebsiteSeriesPoint"},"V1WebsiteVersions":{"properties":{"findings_policy":{"type":"integer","title":"Findings Policy","description":"Scores compare only under one rules version."},"website_policy":{"type":"string","enum":["quick","base","full","subscription"],"title":"Website Policy"},"questions":{"additionalProperties":{"type":"integer"},"type":"object","title":"Questions"},"first_screen_read":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"First Screen Read"},"screens_consistency":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Screens Consistency"},"readiness":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Readiness"},"bands":{"anyOf":[{"$ref":"#/components/schemas/V1WebsiteBands"},{"type":"null"}],"description":"The cut-offs the bands were read with; null where the read kept none."}},"type":"object","required":["findings_policy","website_policy","questions","first_screen_read","screens_consistency","readiness","bands"],"title":"V1WebsiteVersions"},"V1Work":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"paused":{"type":"boolean","title":"Paused"},"read_only_until":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Read Only Until"},"running":{"type":"integer","title":"Running"},"next_check_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"type":"null"}],"title":"Next Check At"},"next_scan_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Scan At"},"jobs":{"items":{"$ref":"#/components/schemas/V1WorkJob"},"type":"array","title":"Jobs"},"operations":{"items":{"$ref":"#/components/schemas/Operation"},"type":"array","title":"Operations","description":"Brand-wide operations with stable identity, agent, status, affected sections, subject, progress, authorized verbs and destination. Chat replies stay private to their conversation."},"reading_progress":{"anyOf":[{"$ref":"#/components/schemas/V1WorkProgress"},{"type":"null"}],"description":"Summed progress of live reading jobs; null when no positive total is measured."},"week":{"$ref":"#/components/schemas/V1WorkCounts"},"since_started":{"$ref":"#/components/schemas/V1WorkCounts"},"analyst_week":{"$ref":"#/components/schemas/V1AnalystWeek"}},"type":"object","required":["meta","paused","read_only_until","running","next_check_at","next_scan_at","jobs","operations","reading_progress","week","since_started","analyst_week"],"title":"V1Work"},"V1WorkCounts":{"properties":{"answers_read":{"type":"integer","title":"Answers Read"},"pages_read":{"type":"integer","title":"Pages Read"},"drafts_written":{"type":"integer","title":"Drafts Written"},"other_jobs":{"type":"integer","title":"Other Jobs"}},"type":"object","required":["answers_read","pages_read","drafts_written","other_jobs"],"title":"V1WorkCounts"},"V1WorkJob":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"kind":{"type":"string","title":"Kind"},"subject":{"type":"string","title":"Subject"},"state":{"type":"string","title":"State"},"live":{"type":"boolean","title":"Live"},"next_check_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"type":"null"}],"title":"Next Check At"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At"},"action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Action Id","description":"The action `get_action` reads for this job; null for the held first scan."},"action_kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Action Kind","description":"The action's `kind`; null for the held first scan."},"holder":{"anyOf":[{"type":"string","enum":["you","heralded","waiting"]},{"type":"null"}],"title":"Holder","description":"Who holds the action, as its `holder` says; null for the held first scan."},"progress":{"anyOf":[{"$ref":"#/components/schemas/V1WorkProgress"},{"type":"null"}],"description":"How far a running scan has got: engines answered of asked."},"current_step":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Step","description":"The job's current step, as `current_step` on `get_action` names it."}},"type":"object","required":["id","kind","subject","state","live","next_check_at","started_at","action_id","action_kind","holder","progress","current_step"],"title":"V1WorkJob"},"V1WorkProgress":{"properties":{"done":{"type":"integer","title":"Done"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["done","total"],"title":"V1WorkProgress"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ValidationIssue":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Loc"},"msg":{"type":"string","title":"Msg"},"type":{"type":"string","title":"Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationIssue"},"ValidationProblem":{"properties":{"type":{"type":"string","title":"Type"},"title":{"type":"string","title":"Title"},"status":{"type":"integer","title":"Status"},"detail":{"type":"string","title":"Detail"},"code":{"type":"string","title":"Code"},"instance":{"type":"string","title":"Instance","default":""},"errors":{"items":{"$ref":"#/components/schemas/ValidationIssue"},"type":"array","title":"Errors"}},"type":"object","required":["type","title","status","detail","code","instance","errors"],"title":"ValidationProblem"},"Verdicts":{"properties":{"agrees":{"type":"integer","title":"Agrees","description":"Answers agreeing with this wording.","default":0},"partly":{"type":"integer","title":"Partly","description":"Answers partly agreeing with this wording.","default":0},"contradicts":{"type":"integer","title":"Contradicts","description":"Answers contradicting this wording.","default":0},"doesnt_say":{"type":"integer","title":"Doesnt Say","description":"Answers that do not address this wording.","default":0},"answers":{"type":"integer","title":"Answers","description":"All answers evaluated against this wording.","default":0}},"type":"object","required":["agrees","partly","contradicts","doesnt_say","answers"],"title":"Verdicts"},"Versus":{"properties":{"key":{"type":"string","title":"Key","description":"The figure, prompt or engine key."},"label":{"type":"string","title":"Label","description":"The display name of the figure, prompt or engine."},"them":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Them","description":"The competitor's value, or null when unmeasured."},"you":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"You","description":"Your brand's value, or null when unmeasured."},"gap":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Gap","description":"Your value minus the competitor's, or null if either is unmeasured."},"lead":{"anyOf":[{"type":"string","enum":["you","them","level"]},{"type":"null"}],"title":"Lead","description":"Which brand leads, or null if either is unmeasured."}},"type":"object","required":["key","label","them","you","gap","lead"],"title":"Versus","description":"One figure for the competitor beside the brand's own. `gap` is yours\nless theirs; it and `lead` are null where either side has no value."},"VersusPage":{"properties":{"rows":{"items":{"$ref":"#/components/schemas/Versus"},"type":"array","title":"Rows"},"total":{"type":"integer","title":"Total"},"offset":{"type":"integer","title":"Offset"},"limit":{"type":"integer","title":"Limit"}},"type":"object","required":["rows","total","offset","limit"],"title":"VersusPage","description":"One page of a pane's lost or won prompts, widest gap first, and how\nmany there are."},"VocabularyOption":{"properties":{"value":{"type":"string","title":"Value"},"label":{"type":"string","title":"Label"}},"type":"object","required":["value","label"],"title":"VocabularyOption","description":"One value of a served vocabulary, with the one word it reads as.\n\nA vocabulary the web used to mirror travels with the data it describes:\nthe response lists its values in their one order, each with its label, and\na value the web does not know renders as its raw id."},"VoiceBox":{"properties":{"state":{"type":"string","enum":["measured","not_measured","not_comparable"],"title":"State"},"population":{"type":"string","enum":["all_answers","weekly_answers","search_keywords"],"title":"Population"},"info":{"type":"string","title":"Info"},"denominator":{"type":"integer","title":"Denominator"},"segments":{"items":{"$ref":"#/components/schemas/VoiceSegment"},"type":"array","title":"Segments"}},"type":"object","required":["state","population","info","denominator","segments"],"title":"VoiceBox"},"VoiceSegment":{"properties":{"kind":{"type":"string","enum":["you","competitor","rest","else"],"title":"Kind"},"brand_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Key"},"label":{"type":"string","title":"Label"},"pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pct"},"numerator":{"type":"integer","title":"Numerator"},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Count"}},"type":"object","required":["kind","brand_key","label","pct","numerator","count"],"title":"VoiceSegment","description":"One part of the share-of-voice bar. `pct` is a whole percent, and the\nsegments add up to 100; null where the read measured no share."},"WaitResponse":{"properties":{"kind":{"type":"string","enum":["answer","agreed","queued","asked","blocked"],"title":"Kind","description":"answer to an email of ours, agreed on a date they gave, queued behind another task to the same contact, asked whether they replied, or blocked on a third party you named."},"on":{"type":"string","title":"On","description":"Who the task waits on."},"due_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Due On","description":"When the wait is due; null when it has no date."},"due_source":{"anyOf":[{"type":"string","enum":["given","default","ours"]},{"type":"null"}],"title":"Due Source","description":"Where the date came from: given by them, Heralded's default, or our schedule; null without a date."},"acts":{"type":"string","enum":["heralded","member"],"title":"Acts","description":"Who acts when the wait is over: heralded or member."},"since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Since","description":"When the wait began."}},"type":"object","required":["kind","on","due_on","due_source","acts","since"],"title":"WaitResponse","description":"What the task waits for."},"WeekTimeline":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total","description":"Observations in the selected week."},"limit":{"type":"integer","title":"Limit","description":"Maximum observations returned."},"offset":{"type":"integer","title":"Offset","description":"Observations skipped."},"week":{"type":"string","format":"date","title":"Week","description":"The Monday starting the week, in UTC."},"rows":{"items":{"$ref":"#/components/schemas/TimelineItem"},"type":"array","title":"Rows","description":"A page of observed events, newest first."},"days":{"items":{"$ref":"#/components/schemas/TimelineDay"},"type":"array","title":"Days","description":"The week's observed days, newest first."}},"type":"object","required":["meta","next_cursor","total","limit","offset","week","rows","days"],"title":"WeekTimeline","examples":[{"week":"2026-10-26","rows":[],"days":[],"total":0,"limit":20,"offset":0,"next_cursor":null,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}}}]},"WeeklyBrief":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","description":"Normalized query and newest included scan."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as cursor with the same query to read the next page; null at the end."},"total":{"type":"integer","title":"Total","description":"Issued decisions in this reader's fixed set."},"limit":{"type":"integer","title":"Limit","description":"Maximum rows returned from each decision list."},"offset":{"type":"integer","title":"Offset","description":"Rows skipped in each decision list."},"today":{"anyOf":[{"$ref":"#/components/schemas/HomeToday"},{"type":"null"}],"description":"The viewer's live Today box."},"scan_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Scan Id","description":"The report this brief issued with; null before issue."},"issued_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Issued At","description":"When this fixed decision set issued."},"done":{"type":"boolean","title":"Done","description":"Every decision in the issued set is answered or no longer applies."},"remaining":{"type":"integer","title":"Remaining","description":"Unanswered decisions in that fixed set, excluding later arrivals."},"decisions":{"items":{"$ref":"#/components/schemas/Decision"},"type":"array","title":"Decisions","description":"A page of the reader's fixed decision set."},"new_since_monday":{"items":{"$ref":"#/components/schemas/Decision"},"type":"array","title":"New Since Monday","description":"A separate page of member turns and suggestions arriving after issue."},"new_total":{"type":"integer","title":"New Total","description":"Current decisions that arrived after issue in this reader's scope."}},"type":"object","required":["meta","next_cursor","total","limit","offset","today","scan_id","issued_at","done","remaining","decisions","new_since_monday","new_total"],"title":"WeeklyBrief","examples":[{"today":null,"scan_id":null,"issued_at":null,"done":false,"total":0,"remaining":0,"decisions":[],"new_since_monday":[],"new_total":0,"limit":20,"offset":0,"next_cursor":null,"meta":{"query":{},"data_as_of":null,"partial":false,"updating":false,"last_attempt_failed":false,"surfaces":{}}}]},"WindowDescriptor":{"properties":{"choice":{"type":"string","enum":["latest","4w","12w"],"title":"Choice"},"reads":{"type":"integer","title":"Reads"},"first_read_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Read At"},"last_read_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Read At"}},"type":"object","required":["choice","reads","first_read_at","last_read_at"],"title":"WindowDescriptor"},"WordBand":{"properties":{"min":{"type":"integer","minimum":1.0,"title":"Min","description":"Fewest words, inclusive."},"max":{"type":"integer","minimum":1.0,"title":"Max","description":"Most words, inclusive."},"stated":{"anyOf":[{"type":"string","enum":["about","range"]},{"type":"null"}],"title":"Stated","description":"Whether they stated one approximate count or an explicit range; null on older bands."}},"type":"object","required":["min","max","stated"],"title":"WordBand"},"WorkCompleted":{"properties":{"state":{"type":"string","enum":["ready","missing","not_set"],"title":"State","description":"Always ready; an empty list is a quiet period."},"items":{"items":{"$ref":"#/components/schemas/CompletedWork"},"type":"array","title":"Items","description":"Delivered in the period, newest first."}},"type":"object","required":["state","items"],"title":"WorkCompleted"},"WorkCounts":{"properties":{"your_turn":{"type":"integer","title":"Your Turn","description":"Non-setup your_input work in the viewer scope, including stopped site checks."},"emails_to_file":{"type":"integer","title":"Emails To File","description":"Unassigned inbound emails waiting for the member to file against work."},"proposed":{"type":"integer","title":"Proposed","description":"Non-setup actions in state new."},"scheduled":{"type":"integer","title":"Scheduled","description":"Non-setup deferred actions plus scheduled Heralded runs."},"scheduled_runs":{"type":"integer","title":"Scheduled Runs","description":"Scheduled Heralded runs."},"working":{"type":"integer","title":"Working","description":"Non-setup actions and Heralded jobs in dispatched."},"waiting":{"type":"integer","title":"Waiting","description":"Non-setup actions in waiting."},"to_do":{"type":"integer","title":"To Do","description":"Your turn plus proposed actions."},"open":{"type":"integer","title":"Open","description":"Non-setup actions in OPEN_STATES."},"setup":{"type":"integer","title":"Setup","description":"Setup actions in OPEN_STATES."},"found_7d":{"type":"integer","title":"Found 7D","description":"Non-setup actions assigned to a team member, created in seven days."},"suggestions_kept":{"type":"integer","title":"Suggestions Kept","description":"Non-setup actions in state kept."}},"type":"object","required":["your_turn","emails_to_file","proposed","scheduled","scheduled_runs","working","waiting","to_do","open","setup","found_7d","suggestions_kept"],"title":"WorkCounts"},"WorkProgressResponse":{"properties":{"done":{"type":"integer","title":"Done"},"total":{"type":"integer","title":"Total"},"unit":{"type":"string","title":"Unit"}},"type":"object","required":["done","total","unit"],"title":"WorkProgressResponse","description":"How far an executing read has got (#2446): engines answered of the\nengines asked. The words are the row's; the pips are the client's."},"WorkRowResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The action or recurring job id."},"tracked_domain_id":{"type":"string","format":"uuid","title":"Tracked Domain Id","description":"Deprecated alias of brand_id.","deprecated":true},"target_entity":{"type":"string","title":"Target Entity","description":"The page, prompt, source or check the work targets."},"write_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Write Language","description":"The writing language code."},"write_language_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Write Language Source","description":"How the language was chosen."},"write_language_locked":{"type":"boolean","title":"Write Language Locked","description":"Whether writing has locked the language.","default":false},"target_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Type","description":"What the target names; null when unknown."},"issue_type":{"anyOf":[{"$ref":"#/components/schemas/IssueType"},{"type":"string","enum":["daily_read","deep_read","inventory_crawl","detection_sweep","search_sweep"]}],"title":"Issue Type","description":"The kind of action or recurring job."},"segment":{"type":"string","title":"Segment","description":"The work's configured segment label."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The act this work proposes or delivers."},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"The finding behind the work; null when absent."},"state":{"type":"string","enum":["new","accepted","in_progress","blocked","looks_resolved","done","verified_no_move","deferred","dismissed","withdrawn"],"title":"State","description":"The action's lifecycle state."},"group":{"type":"string","enum":["new","your_input","dispatched","scheduled","waiting","settled","withdrawn"],"title":"Group","description":"The current work group."},"holder":{"anyOf":[{"type":"string","enum":["you","heralded","waiting"]},{"type":"null"}],"title":"Holder","description":"Who holds the next step; null when nobody does."},"stage":{"type":"string","enum":["observe","decide","do","verify"],"title":"Stage","description":"The work's observe, decide, do or verify stage."},"demand":{"type":"string","title":"Demand","description":"What the work is doing or waiting for."},"member":{"anyOf":[{"type":"string","enum":["writer","publicist","engineer","analyst"]},{"type":"null"}],"title":"Member","description":"The responsible team member; null for setup and prompt replacements."},"waiting_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Waiting Since","description":"When the current ask began; null outside your_input."},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"The first time Heralded started this action. Null on dismissed work."},"delivered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Delivered At","description":"When the result went live, was sent or was published. Null on dismissed work."},"paid_off_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paid Off At","description":"When verification credited a positive measured gain. Null on dismissed work."},"preview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preview","description":"Up to 400 characters of draft opening, email recipient and subject, or planned change while waiting on you."},"outcome":{"anyOf":[{"type":"string","enum":["verified_up","no_move","not_measured","dismissed"]},{"type":"null"}],"title":"Outcome","description":"How settled work ended; null while pending."},"gate":{"anyOf":[{"type":"string","enum":["approval","review"]},{"type":"null"}],"title":"Gate","description":"The review or approval awaited; null otherwise."},"settled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Settled At","description":"When measurement or the decision settled."},"impact_scale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Impact Scale","description":"The measure this action aims to improve."},"expected_impact_pts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expected Impact Pts","description":"Always null: the expected gain is `gain`."},"verified_impact_pts":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Verified Impact Pts","description":"The measured gain credited to the action."},"prompt_movement":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Movement","description":"Whether other work shares the prompt's movement."},"blocked_owner":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blocked Owner","description":"Who the action waits on; null when not blocked."},"check_again_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Check Again On","description":"When to check blocked work again."},"scheduled_for":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Scheduled For","description":"The scheduled start date; null when unset."},"scheduled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Scheduled At","description":"The recurring job's next start."},"repeat":{"anyOf":[{"type":"string","enum":["daily","weekly","thrice_weekly"]},{"type":"null"}],"title":"Repeat","description":"The recurring job's schedule."},"progress":{"anyOf":[{"$ref":"#/components/schemas/WorkProgressResponse"},{"type":"null"}],"description":"The running job's progress."},"platform":{"type":"boolean","title":"Platform","description":"Whether this is Heralded's recurring work.","default":false},"run_state":{"anyOf":[{"type":"string","enum":["scheduled","running","done","skipped","failed","stopped"]},{"type":"null"}],"title":"Run State","description":"The recurring job's current run state."},"assignee":{"anyOf":[{"$ref":"#/components/schemas/AssigneeResponse"},{"type":"null"}],"description":"The person accountable for the work."},"intent_bucket":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent Bucket","description":"The targeted prompt intent; null when absent."},"looks_resolved_evidence":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Looks Resolved Evidence","description":"Evidence for a resolution awaiting confirmation."},"not_seen_since_run":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Not Seen Since Run","description":"The first report that stopped seeing the finding."},"placed_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Placed Position","description":"The member's place in the proposal order."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When the action was marked done."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When this work was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When this work last changed."},"primary_verb":{"anyOf":[{"type":"string","enum":["dispatch","take","done","defer","dismiss","confirm","reject","restore","block","unblock","reopen"]},{"type":"string","const":"review"},{"type":"null"}],"title":"Primary Verb","description":"The main offered action; null when none is offered."},"setup_link":{"anyOf":[{"$ref":"#/components/schemas/SetupLink"},{"type":"null"}],"description":"Where to complete this setup task."},"secondary_verbs":{"items":{"type":"string","enum":["dispatch","take","done","defer","dismiss","confirm","reject","restore","block","unblock","reopen"]},"type":"array","title":"Secondary Verbs","description":"Other offered actions, in menu order."},"return_group":{"anyOf":[{"type":"string","enum":["new","your_input","dispatched","scheduled","waiting","settled","withdrawn"]},{"type":"null"}],"title":"Return Group","description":"The work group a return action resumes."},"job":{"$ref":"#/components/schemas/JobResponse","description":"The work's steps and available controls."},"note":{"anyOf":[{"$ref":"#/components/schemas/TaskNote"},{"type":"null"}],"description":"Task explanation with a live job step."},"credit_cost":{"type":"integer","title":"Credit Cost","description":"Content credits needed to dispatch this work."},"credits_spent":{"type":"integer","title":"Credits Spent","description":"Content credits charged to this work and not refunded."},"dispatchable":{"type":"boolean","title":"Dispatchable","description":"Whether Heralded can execute this work."},"draft_in_flight":{"anyOf":[{"type":"string","enum":["drafting","redrafting"]},{"type":"null"}],"title":"Draft In Flight","description":"Whether a first draft or redraft is being written."},"grounds":{"anyOf":[{"$ref":"#/components/schemas/GroundsResponse"},{"type":"null"}],"description":"What the work rests on; null on Heralded's own work and on work filed before actions carried their grounds."},"done_when":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Done When","description":"When the work is done; null on Heralded's own work."},"tracking":{"items":{"type":"string","enum":["live","crawled","ranked","search_console","cited","moved"]},"type":"array","title":"Tracking","description":"What Heralded tracks once the work is live: live, crawled, ranked, search_console, cited, moved."},"first_citation":{"anyOf":[{"$ref":"#/components/schemas/FirstCitation"},{"type":"null"}],"description":"First qualifying citation of the delivered page."},"citation_count":{"type":"integer","title":"Citation Count","description":"Distinct engine and prompt citation pairs before the list cap.","default":0},"gain":{"anyOf":[{"$ref":"#/components/schemas/GainResponse"},{"type":"null"}],"description":"The expected gain: its band and what the work aims at. Null on Heralded's own work."},"focus":{"anyOf":[{"$ref":"#/components/schemas/FocusTag"},{"type":"null"}],"description":"The starred topic or competitor the work serves, or outside your focus. Null when the brand has no starred topic or competitor, and on Heralded's own work."},"kind_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind Tag","description":"A tag on the kind of work, shown beside its state, such as Sponsored. Null on work that has none."},"ending":{"anyOf":[{"$ref":"#/components/schemas/EndingResponse"},{"type":"null"}],"description":"How the task ended: its key, its words and when. Null while it is open."},"wait":{"anyOf":[{"$ref":"#/components/schemas/WaitResponse"},{"type":"null"}],"description":"What the task waits for, on whom and until when. Null while it waits on nobody."},"brand_id":{"type":"string","format":"uuid","title":"Brand Id","description":"The brand this work belongs to.","readOnly":true},"route":{"type":"string","enum":["home","actions","prompts","search","market","sources","content","perception","audit"],"title":"Route","description":"The Command Center page this work concerns.","readOnly":true}},"type":"object","required":["id","tracked_domain_id","target_entity","write_language","write_language_source","write_language_locked","target_type","issue_type","segment","title","detail","state","group","holder","stage","demand","member","waiting_since","started_at","delivered_at","paid_off_at","preview","outcome","gate","settled_at","impact_scale","expected_impact_pts","verified_impact_pts","prompt_movement","blocked_owner","check_again_on","scheduled_for","scheduled_at","repeat","progress","platform","run_state","assignee","intent_bucket","looks_resolved_evidence","not_seen_since_run","placed_position","completed_at","created_at","updated_at","primary_verb","setup_link","secondary_verbs","return_group","job","note","credit_cost","credits_spent","dispatchable","draft_in_flight","grounds","done_when","tracking","first_citation","citation_count","gain","focus","kind_tag","ending","wait","brand_id","route"],"title":"WorkRowResponse","description":"One row of work, as the product reads it.\n\nThe projection fields (`group`, `holder`, `stage`, `demand`) come from\n`project_work` and nothing else, so no consumer re-derives them from\n`state`. Severity and confidence are deliberately absent: priority is\nsystem-owned and neither is ever shown as a field (D12)."},"WorkSubject":{"properties":{"action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Action Id","description":"The action this work serves."},"piece_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Piece Id","description":"The Studio piece being prepared."},"prompt_uid":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Prompt Uid","description":"The tracked prompt being read."},"keyword_uid":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Keyword Uid","description":"The keyword being checked."},"segment_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Segment Id","description":"The segment being researched."},"scan_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Scan Id","description":"The report or read carrying this work."},"binding_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Binding Id","description":"The brand connection being checked."}},"type":"object","required":["action_id","piece_id","prompt_uid","keyword_uid","segment_id","scan_id","binding_id"],"title":"WorkSubject"},"WorkspaceUsage":{"properties":{"month_start":{"type":"string","title":"Month Start"},"period_start":{"type":"string","title":"Period Start"},"period_end":{"type":"string","title":"Period End"},"entitlement_source":{"anyOf":[{"type":"string","enum":["stripe","partner"]},{"type":"null"}],"title":"Entitlement Source"},"plan":{"anyOf":[{"type":"string","enum":["core","plus"]},{"type":"null"}],"title":"Plan"},"paid_by":{"type":"string","enum":["self","manager","partner"],"title":"Paid By","default":"self"},"manager_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Manager Name"},"included_managed_accounts":{"type":"integer","title":"Included Managed Accounts"},"prompts":{"$ref":"#/components/schemas/UsagePrompts"},"topics":{"$ref":"#/components/schemas/UsageCapacity","description":"Active topics of reading brands in live profiles, and the topic limit."},"brand_capacity":{"$ref":"#/components/schemas/UsageCapacity","description":"Unarchived, reading brands across the organisation, and its brand limit."},"content_credits":{"$ref":"#/components/schemas/UsageContentCredits"},"agent_answers":{"anyOf":[{"$ref":"#/components/schemas/AgentAnswers"},{"type":"null"}]},"brands":{"items":{"$ref":"#/components/schemas/UsageBrand"},"type":"array","title":"Brands","default":[]}},"type":"object","required":["month_start","period_start","period_end","entitlement_source","plan","paid_by","manager_name","included_managed_accounts","prompts","topics","brand_capacity","content_credits","agent_answers","brands"],"title":"WorkspaceUsage"},"WriterReport":{"properties":{"resolved_questions":{"items":{"type":"string"},"type":"array","title":"Resolved Questions","description":"Questions answered or dismissed by a member on this piece."},"questions":{"items":{"type":"string"},"type":"array","title":"Questions","description":"Questions the brand can answer; none blocks approval."},"sources":{"items":{"$ref":"#/components/schemas/RecordedSource"},"type":"array","title":"Sources","description":"Material the writer recorded for this piece."},"references":{"items":{"$ref":"#/components/schemas/RecordedReference"},"type":"array","title":"References","description":"Passages checked against the recorded sources."}},"type":"object","required":["resolved_questions","questions","sources","references"],"title":"WriterReport"}},"securitySchemes":{"serviceToken":{"type":"http","description":"An organisation service token, sent as Authorization: Bearer hrld_svc_... Scopes: scans:start starts service scans; scans:read reads them; managed:read reads brands, profile, overview, scores, competitors, actions and Snapshots in actively managed organisations; managed:share makes their restricted Snapshots unlisted.","scheme":"bearer"},"apiKey":{"type":"http","description":"An API key, sent as `Authorization: Bearer hrld_...`.","scheme":"bearer"}}}}