Skip to main content

​
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 addition with its date. 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.

​
The score version

The one meaning that can change within v1 is the scale of heralded_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 compares the period with preceding reports, as many as the period holds and at least four when available. A change never spans two score versions and is null while the baseline comparison crosses a refit. Figures in the API describes the baseline and its states.
  • Only reads on the current score version, v7.0, are served. Reads on older score versions do not appear in the Command Center.
The calibration in use today was measured on 47 sites and will be refit on a larger set. How the scale was measured has the detail. Snapshot reports on score version v7.0 remain available. Older reports return a 410 response with code scan_version_unsupported and need a new Snapshot.