Skip to main content
Within v1, Heralded adds routes, fields, MCP tools and enum values and never removes them. 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 2026-10-05: Trend instrument keys add nullable passes. A recorded pass-count change prevents comparison; a missing count keeps comparisons unchanged. See 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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 and Connect an assistant.
  • 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?.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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 and 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.