Versioning and deprecation

The API is versioned in the path: https://api.rtcstats.com/v1.0/.... The version covers the shape of the contract, not the analysis behind it.

A new major or minor version gets a new path prefix and runs alongside the existing one. We do not silently change the meaning of an existing path.

These require a new version:

• Removing an endpoint, or removing a field from a response
• Renaming a field, an operationId, or an enum value
• Narrowing a type, or making an optional request field required
• Changing the HTTP status code returned for an existing condition
• Changing what an existing errorCode means

These do not, and can land in the current version at any time:

• Adding an endpoint, a response field, or an optional request parameter
• Adding a new observation type, severity value or tag. The observation catalog grows continuously; treat it as open. Read it from GET /v1.0/observations rather than hard-coding a list.
• Improving the analysis, the scores, or the AI summary for a given dump
• Performance, wording and documentation changes

Write your client so an unknown field or an unknown observation type is ignored rather than fatal. That single habit removes most of the reasons you would ever need to care about this page.

• Six months minimum between announcing that a version is deprecated and switching it off.
• Three months for an individual endpoint or field within a live version, where a direct replacement already exists.
• No notice only where we have to act immediately on a security problem. If that happens we will say what and why on the changelog.

Announcements go to the changelog, to the account owner by email, and into the OpenAPI description before they take effect.

Machine-readable, so an agent can notice without reading this page:

• The operation is marked deprecated: true in the OpenAPI description, with a description naming its replacement and its removal date.
• Responses carry the Deprecation and Sunset HTTP headers (RFC 9745 and RFC 8594), plus a Link header with rel="deprecation" pointing at the explanation.

Announced in human-readable form too, in two places:

• The release blog post for that version, under Ecosystem Updates → API & MCP.
• The changelog, tagged [Breaking Changes].

If you run an autonomous client, check for a Sunset header on every response and surface it. A deprecation nobody reads is a deprecation that becomes an outage.

The Model Context Protocol server follows the MCP specification's own version negotiation, sent in the MCP-Protocol-Version header. We support the protocol versions listed in the error message returned for an unsupported one.

The open-source collector (rtcstats-js and rtcstats-server) is versioned in its own repository and released independently of the hosted API.