Changelog

Contract changes only: routes, tool definitions, envelope shape, error codes, wire formats. Entries are written against the generated artefacts, so a change that does not appear in /v1/openapi.json or the MCP tool catalogue does not appear here either.

The API is versioned with semver; the MCP protocol revision is date-versioned. Breaking changes require a new major and are labelled as such.

Unreleased

The service is pre-1.0 and has not been published. Everything below describes the contract as it will first ship.

Wire format

• POST /v1/digital-links/resolve takes uri, not url. The documented field and the served field had diverged; the code now generates the contract, so they cannot again.
• Timestamps are RFC 3339 strings. They were previously serialised as an array of integer components, which no date parser accepts.
• trust_level is a label — "L0" through "L5" — everywhere it appears, in responses and in query parameters alike. It was previously an integer in responses.
• request_id is a ULID prefixed req_, matching ^req_[0-9A-HJKMNP-TV-Z]{26}$.

Envelope

• status may be found, not_found, unknown, ambiguous or partial.
• claims and sources are top-level arrays, not nested inside data.
• meta.snapshot_id does not exist. It was required by the published schema and never emitted by the service; it returns when evidence snapshots are versioned.
• Batch responses carry their results under data.results.

Errors

• 17 error codes, listed in Errors. Every one is reachable, and no reachable code is undocumented.
• 401 and 500 responses are RFC 9457 application/problem+json, like every other error. They previously used a different shape.
• retryable reflects the actual code. It was hardcoded false, including on 429.

Surfaces

• 13 REST routes, including /v1/whoami and /v1/mcp, which were served but undocumented.
• 6 MCP tools. Eight are specified; two are not built and are no longer listed as if they were.