Command Center updates
When a new version is available, the Command Center offers Refresh. Choose it when you are ready to reload. Heralded never refreshes the page automatically, so you can finish what you are typing first. Close the notice to hide it until the next release.The API version
Every route sits under/v1, and the MCP server at /v1/mcp serves the same data. Within v1, Heralded may add routes, fields, MCP tools, and new values to enums such as engine and group. Build clients that ignore fields they don’t recognise and handle enum values they haven’t seen. Heralded renames or removes a field or route only under a new version prefix. The API changelog lists each change with its date.
The changelog lists accepted pre-launch removals within v1.
The public OpenAPI document defines the contract. First-party display fields absent from that document, such as composed sentences, enum labels, menus and cards, are not API fields. API keys and MCP receive data only; the signed-in Command Center keeps its display fields. Additions to data remain compatible when you ignore unfamiliar fields.
A new optional parameter keeps the behavior you received before it existed when you omit it. Changes to a field’s meaning appear both here and in the changelog.
On 9 October 2026, the topics read changed. /topics lists the topics you track instead of the content check’s topics, so a topic’s id is its UUID and a topic can have a null status. The changelog lists what changed; Topics describes the read.
On 9 October 2026, the reputation read changed. In /overview and MCP get_brand_overview, understood and praised weigh the pages AI cites and Google ranks that name the brand beside the AI answers, so they can differ from /scores. The changelog lists what changed; Reputation describes the read.
On 22 October 2026, the Heralded Score changed to AI answers only. In overview, scores, competitors and topics, all equals ai for the score, Mentioned and Recommended. Search keeps its shares and returns heralded_score with a null value and state not_scored. Keyword score and trend are null too. Every stored report reads the same way, so this introduces no history break. Figures in the API describes the contract; the changelog records the change.
On 25 October 2026, question and engine panes changed answer_count to null for Understood. Its share averages partial credit, so it has no count of perfect matches. The changelog records the change; Figures in the API describes the field.
On 31 October 2026, competitor website changes changed. Without change, they are the week’s moves, one per competitor and change type; with change, each page of that type. Files such as PDFs no longer count as pages. The changelog records the change; Figures in the API describes the read.
On 8 November 2026, GET /v1/scans/{scan_id} and MCP get_scan with scan_id changed how they read a Snapshot whose profile waited 24 hours without a run: from state: failed with failure_reason: brief_abandoned to state: expired with a null failure_reason. Scan lists keep failed with brief_abandoned. The changelog records the change; Scans in the API describes the states.
On 14 November 2026, Sources citation change.delta changed to a whole citation count. Change state and direction follow the rounded delta. Confidence bounds and real keep their meaning. The changelog records the change; Figures in the API describes the fields.
On 18 November 2026, an action’s thread events and grounds changed. Each event’s summary is its line for no reader in particular, rather than the sentence stored when it happened. grounds.evidence leaves out the observation grounds.cause states. note.whats_happening no longer ends with the lead’s date, which grounds.observed_at carries, and note.why_it_matters is null when the work states no reason. The changelog records the change; Action fields describes the fields.
On 22 November 2026, mode was removed from brands, scans, shared Snapshots, the brand profile and every trend key, and audience_type from audiences. sells_to and ecommerce replace mode, and have been returned beside it since 20 November 2026. Heralded’s own products were the only consumers of mode. The changelog records the change; Figures in the API describes the scan fields.
The OpenAPI document is public at https://api.heralded.ai/v1/openapi.json. The API reference is built from a copy of it, and a check on every change keeps the two in step. The MCP protocol versions the server answers are listed under Connect an MCP client.
Text search
Answers and questions useq as their only text-search parameter in REST and MCP.
The score version
The one meaning that can change within v1 is the scale ofheralded_score. It sits on a calibrated scale measured from real brands, and when Heralded refits that scale, the result is a new score version. Two things follow:
- Period figures pool comparable reports over your selected
period. The descriptor gives their report count, answer dates and how many reports a change of instrument excluded. Change follows the baseline and paired-test rules from the second comparable report. A change never spans two served score versions. Figures in the API describes the baseline and its states. - The current score version is v9.1. The Search side weights keywords within their countries and keeps unfinished countries unknown. New weekly reports with keyword checks use v9.1, with
sidesaiandsearchin their instrumentkey. Stored v9.0 reports keep their frozen weights and version. A change never spans v9.0 and v9.1. Reads without Search measurements stay on v8.0. The AI side of stored Command Center reads, leaderboard months and issued Snapshot reports is recomputed from frozen per-answer facts on v8.0. A read without per-answer facts keeps its issued score and version.
code scan_version_unsupported and need a new Snapshot. Emails and share images already sent keep their original figures.