> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heralded.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API changelog

> Every addition to the v1 API, newest first.

Within v1, Heralded adds routes, fields, MCP tools and enum values and never removes them. [Versioning](/versioning) states the rules. Each addition appears here with its date.

* **2026-10-06:** Only score version v7.0 is served. A shared scan on v6.0 now returns `410` with `code` `scan_version_unsupported`, as older versions already did. See [Versioning](/versioning#the-score-version).
* **2026-10-06:** The legacy `/public/categories` routes are removed. Read public leaderboards through `/v1/leaderboards`, including facets and brand and source details. See [Leaderboards](/concepts/leaderboards).
* **2026-10-05:** Public leaderboard sources, cited pages, brand sources, questions and quotes withhold a stable sample keyed by entity kind, identity and measurement month. The bottom 70% of the SHA-256 range is withheld, with position 1 always sent and positions beyond 20 omitted. The existing `withheld` field reports the withheld positions in the full list. Totals and response shapes stay unchanged. REST and MCP use the same sample, including brand and source pages. See [What the public leaderboards show](/concepts/leaderboards#what-the-public-leaderboards-show).
* **2026-10-05:** The brand leaderboard read and MCP `get_leaderboards` add `questions` with per-question place and named competitors, `engine_ranks` with average rank, ranked leaderboard count and best rank, `highlights` with selected sentence quotes and their question and leaderboard context, and `history_series` with monthly score, Mentioned and Recommended values per placement. Each new module has its own paging offset. Existing `won`, `missed`, `competitors`, `engines`, `history` and their paging parameters remain available. `evidence` keeps its row shape and selects the same quotes as `highlights`. See [Brand and source pages](/concepts/leaderboards#brand-and-source-pages).
* **2026-10-05:** Leaderboard sources, cited pages, a brand's sources and questions won and missed, and evidence quotes add `withheld` and send only positions 1–2 and 7–20, with positions 3–6 withheld on the server. Totals count the full list, offsets keep their original positions, and these modules stop paging at position 20. Rankings, engine lists, placements, competitors and history keep ordinary paging. MCP `get_leaderboards` follows the same rule. See [What the public leaderboards show](/concepts/leaderboards#what-the-public-leaderboards-show).
* **2026-10-05:** Leaderboard facet combinations add nullable `featured_position`, the curated display order for measured combinations. MCP `get_leaderboards` returns the same field. See [Leaderboards](/concepts/leaderboards).
* **2026-10-05:** Leaderboard brand rows add `engines`, each engine's Mentioned and Recommended for the filter, with `null` values where the engine did not read the brand. Source rows add `answers`, the answers in the filter citing the source, beside `citations`. Question rows add `language`. MCP `get_leaderboards` returns the same fields. See [Leaderboards](/concepts/leaderboards).
* **2026-10-05:** Public leaderboard reads add `GET /v1/leaderboards`, `/leaderboards/facets`, `/leaderboards/brands/{slug}` and `/leaderboards/sources/{domain}`, with published measurements, independently paged modules, IP and site-key limits, caching and revalidation. MCP adds token-authenticated `get_leaderboards` over the same reads. See [Leaderboards](/concepts/leaderboards).
* **2026-10-05:** Trend instrument keys add nullable `passes`. A recorded pass-count change prevents comparison; a missing count keeps comparisons unchanged. See [Change](/methodology/change#when-there-is-no-change).
* **2026-10-05:** Single pages and MCP `get_page` add `funnel_series`, the funnel on each weekly report's 28-day window, oldest first, back as far as your plan's history reads. Each point carries `start`, `end`, `search_clicks`, `crawled`, `fetched_live`, `cited` and `ai_visits`, with `null` for a measurement the report did not record. See [Pages, topics and Audit](/figures#pages-topics-and-audit).
* **2026-10-05:** One page and MCP `get_page` add `takes`, with `with_takes`, `takes_limit` and `takes_offset`: the passage each answer lifted from the page and the claim it supported, one per prompt and engine. Takes are kept with each scan, so `as_of` returns the same takes after a page edit, a later scan or answer-text expiry. `unavailable` counts citing answers whose take could not be kept. See [Pages, topics and Audit](/figures#pages-topics-and-audit).
* **2026-10-04:** Page funnel windows add `history_days` and `clamped`. Crawler, Visits from AI and Search Console measurements read back 90 days on Core and 13 months on Plus, `as_of` pins included, and a funnel on an older report has `null` for them. See [History](/concepts/usage#history).
* **2026-10-04:** Shared scans add `source_tier_rollups[].citation_share_pct` and `brand_citation_summary.owned_share_pct`, `competitor_share_pct` and `independent_share_pct`. Race rows add `gap_pts`, the row's Heralded Score minus the subject's. See [Scans](/figures#scans).
* **2026-10-04:** Segment engine rows add `figure`, and engine-screen Mentioned and Recommended cards add `kpis[].figure`, in the API and MCP `get_segments`. They share the answer-based values, ranges and measurement states of scores filtered to the segment and grouped by engine over `1w`. See [Segments in the API](/concepts/segments#read-segments-through-the-api).
* **2026-10-04:** `GET /v1/brands/{brand_id}/scores` and `/competitors`, with MCP `get_scores` and `list_competitors`, accept `cursor` and return `next_cursor` for the Engines table, engine pane competitors and Competitors leaderboard they page. `GET /v1/organizations/{organization_id}/brands` rows add `data_as_of`, the scan their figures read, to pass as `as_of` to that brand's reads. MCP `list_portfolio` serves the organization's portfolio. See [Errors and limits](/errors-and-limits) and [Connect an assistant](/connect-mcp#tools).
* **2026-10-04:** Audit page rows and MCP `get_audit` add a fifth access gate, `ai_crawler_refused`. It fails where Cloudflare verified that an AI crawler was refused on the page or got not found from a live page. Changes and MCP `list_changes` add the insight kind `ai_crawler_refused`, whose work is a `technical_fix` action. See [Can AI read your site?](/concepts/site-readability#website-in-the-command-center).
* **2026-10-04:** Page funnels add `crawler_bots`, counting served requests per bot with verification true or unknown, including search engines. Known-unverified AI requests remain in `funnel.unverified`; existing all-served bot totals keep their meaning. See [Pages, topics and Audit](/figures#pages-topics-and-audit).
* **2026-10-04:** Owned page lists, single pages, Audit page rows and MCP `get_page` add `funnel`, with one dated window for search clicks and impressions, AI crawls, live fetches, citations, Visits from AI, blocked, not-found and unverified requests, search-engine crawls and crawler sources. Unmeasured counts are `null`; WordPress requests with unknown verification count toward AI crawls and live fetches. See [Pages, topics and Audit](/figures#pages-topics-and-audit).
* **2026-10-04:** Page crawler breakdowns add `category`, also served by MCP `get_page`. Counts use daily source precedence so a connection outside the plugin replaces overlapping plugin counts. See [Pages, topics and Audit](/figures#pages-topics-and-audit).
* **2026-10-04:** `GET /v1/brands/{brand_id}/prompt-suggestions` and MCP `list_prompt_suggestions` add `suggestions`, the picker's list for tracking a new prompt, with each entry's `text`, `intent_label` and `reason`. It is not paged and does not change `items`. See [Connect an assistant](/connect-mcp#tools).
* **2026-10-04:** Single prompts and MCP `get_prompt` add each engine's display name and the four measured states for its latest answer, including its answer id and read date. The facts follow the same latest-answer rule and `as_of` scan pin as the existing engine state. See [Prompts](/figures#prompts).
* **2026-10-04:** One owned page, topic and competitor, including their MCP reads, add `citation_evidence` and `unavailable_scans`. Rival-page panes add the same fields and `measurement` `unavailable` when the period has incomplete citations and no evidence for a known rival's page. See [Figures in the API](/figures#pages-topics-and-audit).
* **2026-10-04:** Sources and MCP `list_sources` accept `sort=priority` and return each site's `priority` position and `priority_reason`. `with_summary=true` adds up to three actionable `worth_pursuing` suggestions and `worth_pursuing_total`. See [Sources in the API](/figures#sources).
* **2026-10-04:** `GET /v1/brands/{brand_id}/changes`, `/prompt-suggestions` and MCP `list_changes` and `list_prompt_suggestions` accept `cursor` and return `next_cursor`. See [Errors and limits](/errors-and-limits).
* **2026-10-04:** Work jobs and MCP `get_work` add `holder`, who holds the job's task, with the same values as `holder` on actions. See [Task fields](/concepts/actions#task-fields).
* **2026-10-04:** Before launch, every `answers_link` drops its `total`: it carries the `href` or `url` of the answers alone, and the Answers page owns the count. This covers every `/v1` read and MCP tool that returns one.
* **2026-10-04:** The overview and MCP `get_brand_overview` add `heralded_score_band`, `score_bands`, `score_context`, `since_started` and `verified_actions`, and `with_diagnosis=true` adds `diagnosis`. One action and MCP `get_action` accept `as_of` and add the task's state, verbs, job, costs, impact, demand, schedule, assignee, current draft and its recipient, the application's planned value and effect, and the weekly reports that raised it. Work jobs add `action_id`, `action_kind`, `progress` and `current_step`. The overview and Changes pin the latest completed scan by default, daily updates included, and name it in `meta.data_as_of`; the overview's figures still describe the weekly reports in the period. Changes under that pin include the daily updates since the latest weekly report, as Home does. See [Figures in the API](/figures#reads) and [Task fields](/concepts/actions#task-fields).
* **2026-10-04:** `GET /v1/shared/scans/{share_id}` can answer `410` with `code` `report_retired`, `domain` and `rescan_url` for a report retired with Heralded's pre-launch data. See [Errors and limits](/errors-and-limits).
* **2026-10-04:** `cited_page_key` on the answers list and MCP `list_answers`: the document key of the page the `cited_page` filter matched. See [Prompts and answers in the API](/figures#prompts).
* **2026-10-04:** Prompt list cursors issued before 4 October 2026 return `400 invalid_cursor`; request the first page again.
* **2026-10-03:** Perception, scores, sources, cited pages, owned pages, topics and Audit add the labels, summaries, menus and evidence their pages and panes show. Scores add opt-in axis panes; owned pages add opt-in Search Console metrics. Lists add search, sorting and evidence paging. The existing MCP tools return the same fields and accept the same parameters. See [Figures in the API](/figures).
* **2026-10-03:** Before launch, `/v1` source ownership counts discovered competitors' sites as rival-owned. This includes non-channel brands discovered across the selected period with at least three naming answers, alongside the competitors you track today. Sources, cited pages, engine panes and MCP use the same ownership. See [Sources](/concepts/sources).
* **2026-10-03:** Scores and MCP `get_scores` add optional Engines table and pane reads, with counts, sentences, prompt evidence and sources. Competitors and MCP `list_competitors` add filters and an optional page read with leaderboard, discovered cells, share-of-voice bar and brand roster capacity. One competitor and MCP `get_competitor` add measurement and comparison sentences, capacity, answers link and an optional rival-page pane with its explanation, prompts and queued actions, including daily-only discoveries under the same scan pin. See [Figures in the API](/figures#filters-and-groups).
* **2026-10-03:** Prompt lists add the composed `status_note` for paused and archived prompts and `cells` with their engine readings, answer ids and measured-day labels. MCP `list_prompts` returns the same fields. See [Prompts](/figures#prompts).
* **2026-10-03:** Prompts add period scores, trends, engine marks, taxonomy, filter menus and table selection. Single prompts add the composed sentence, tiles, engine cards and linked work. Answers add four-axis states, highlights, citation titles, filter menus and table selection; single answers accept `as_of`. Scores add optional `cards` for the Prompts band. The existing MCP tools return the same additions. See [Prompts and answers in the API](/figures#prompts).
* **2026-10-03:** Brand settings and MCP `get_settings` add `prompts_used`, the brand's active prompt count, and `prompts_reserved`, its current reservation or `null` for the shared pool. Brand grants can read this meter. Organization usage still requires organization access. See [Usage in the API](/concepts/usage#api-and-assistants).
* **2026-10-03:** Segment reads add the complete comparison table, a segment's figures, trend and prompt evidence, and its selected engine's prompt answers. Read them through `GET /v1/brands/{brand_id}/segments`, `/segments/{segment_id}` and `/segments/{segment_id}/engines/{engine_id}`, or MCP `get_segments`. See [Segments in the API](/concepts/segments#read-segments-through-the-api).
* **2026-10-03:** Read the Content read of a Snapshot or Audit you ran through `GET /v1/scans/{scan_id}/audit`: every audited page ranked best fix first with what it fails, the page checks, the site's readability and the topics the site has no page for. Only the account that ran the scan reads it, and the shared read of a Snapshot never carries it. MCP `get_audit` takes `scan_id` in place of `brand` for the same read. See [Scans in the API](/figures#scans).
* **2026-10-03:** List the Snapshots you ran through `GET /v1/scans`, with the rows, paging and cursor of a brand's scan list. Scan rows add `domain`, `share_id`, `progress_pct` and `failure_reason`, one of `stuck_no_progress`, `brief_abandoned`, `insufficient_engine_signal`, `cost_cap_exceeded`, `report_inputs_missing` or `other` on a failed scan, and `GET /v1/scans/{scan_id}` adds `failure_reason`. See [Scans in the API](/figures#scans).
* **2026-10-03:** Answers add an optional `period` to `GET /v1/brands/{brand_id}/answers` and MCP `list_answers`. Omitting it keeps all weekly and daily answers. Finished answers read frozen measurements. Brands named in answers now come from the detection frozen with each scan, not a text match: the `names` filter matches the brands detected in an answer and the tracked competitors it names, and `rivals_named` uses the frozen detection.
* **2026-10-03:** Read brand profiles, owned domains, tracked competitors, autonomy, connection status and segment configuration through `GET /v1/brands/{brand_id}/settings` and `/segments`, with MCP `get_settings`. Organization members can read prompt and credit use through `GET /v1/organizations/{organization_id}/usage` and MCP `get_usage`. `GET /v1/organizations/{organization_id}/brands` returns portfolio rows with the last week's figures, paired changes and actions waiting; `managed=true` selects the manager's active managed accounts. Brand grants alone open neither organization read.
* **2026-10-03:** List a brand's weekly reports, daily updates and Snapshot through `GET /v1/brands/{brand_id}/scans`, and read one scan's progress or issued Heralded Score, Mentioned, Recommended and readiness through `GET /v1/scans/{scan_id}`, with MCP `get_scan`. Read a delivered report as its link holders see it, with no API key, through `GET /v1/shared/scans/{share_id}`. See [Scans in the API](/figures#scans).
* **2026-10-03:** `GET /v1/brands/{brand_id}/overview` and MCP `get_brand_overview` add `next_weekly_scan_at`, `next_daily_scan_at`, `daily_scans_since_weekly`, `open_action_count` and `readiness`. See [Figures in the API](/figures).
* **2026-10-03:** Read Perception's statement, positioning rows, claims with their verdicts and trend, negative prompts and sources, and best quotes through `GET /v1/brands/{brand_id}/perception`. Read one claim through `/perception/claims/{claim}`. MCP `get_perception` serves either read with an optional `claim` key. Both accept the period, shared figure filters and `as_of`. See [Perception in the API](/figures#perception).
* **2026-10-03:** Sources adds `read_pages_naming_you`, citation share, answers citing, authority and opportunity score. Sources reads report citation evidence availability and how many reports lack it; unavailable counts and history points are blank. `citations_naming_you` is deprecated and keeps counting all citations naming you, including unread pages. Sources and cited-page rows accept shared filters, including `engine`. Read a site's pane through `GET /v1/brands/{brand_id}/sources/{domain}` and `get_source`, and cited-page rows through `GET /v1/brands/{brand_id}/cited-pages` and `list_cited_pages`. Overview's top sources add citation share and the read-pages naming-you count.
* **2026-10-03:** Read one task's steps, thread, drafts, application state and evidence through `GET /v1/actions/{action_id}` and MCP `get_action`. Read agent jobs, the next scan, weekly tallies and the Herald's week through `GET /v1/brands/{brand_id}/work` and MCP `get_work`. See [Task fields](/concepts/actions#task-fields).
* **2026-10-03:** Read one competitor through `GET /v1/brands/{brand_id}/competitors/{key}` and MCP `get_competitor`, with score, trend, head-to-head figures, prompts won and lost, engines, cited pages and tracked since. Competitor lists include discoveries across the selected period and add a separate `channels` list.
* **2026-10-03:** `GET /v1/brands/{brand_id}/scores` and `get_scores` take `engine`, `type`, `intent`, `topic`, `segment` and `prompt` filters and a `group_by` of `engine`, `intent`, `type`, `topic`, `segment`, `prompt` or `competitor`. A grouped read adds `groups`, each with its `group` and its five figures. See [Figures in the API](/figures#filters-and-groups).
* **2026-10-03:** Read your own pages through `GET /v1/brands/{brand_id}/pages` and `/pages/{page_id}`, Content's topics through `GET /v1/brands/{brand_id}/topics` and `/topics/{topic_id}`, and Audit through `GET /v1/brands/{brand_id}/audit`, with MCP `get_page`, `get_topics` and `get_audit`. AI visits read the newest weekly report in the period that read the GA4 property connected now.
* **2026-10-03:** Read one prompt's period score and trend, each engine's latest answer, competitors, top sources, tracking date and status through `GET /v1/brands/{brand_id}/prompts/{prompt_uid}` and MCP `get_prompt`.
* **2026-10-03:** In `GET /v1/brands/{brand_id}/competitors` and `list_competitors`, `share_of_voice_pct` and a `share_of_voice` row's `pct` are `null` for a tracked competitor that no answer in the period asked about or named, where they read 0.
* **2026-10-03:** Computed reads add normalized query metadata and an `as_of` scan pin. Prompts, answers, sources, AI visits and actions add cursor pagination. MCP tools accept the same parameters and return the same metadata. Authenticated responses state their rate limit, 429 bodies carry its numbers, and REST problems include the request id. See [Errors and limits](/errors-and-limits).
* **2026-10-03:** Read Home's Changes through `GET /v1/brands/{brand_id}/changes` and MCP `list_changes`. Read Discover recommendations, provenance, form and demand through `GET /v1/brands/{brand_id}/prompt-suggestions` and MCP `list_prompt_suggestions`.
* **2026-10-02:** Every response has `Cache-Control: private, no-store`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.