> ## 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.

# Versioning

> What can change in the API within v1, and how score versions work.

## 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](/changelog) lists each addition with its date.

The OpenAPI document is public at `https://api.heralded.ai/v1/openapi.json`. The [API reference](/api-reference/v1/get-brands) 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](/connect-mcp#protocol).

## 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](/methodology/heralded-score#score-versions). 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](/figures#change) 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](/methodology/heralded-score#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.


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