Versioning

The API is versioned in the path: /v1/. That prefix is the compatibility boundary.

Within v1, these will not change

• An existing field will not be removed or renamed.
• A field’s type will not change.
• An endpoint will not change its path or method.
• A status code will not change meaning for the same condition.

These can change without a new version

• New fields may be added to responses. Do not write clients that reject unknown fields.
• New optional parameters may be added to requests.
• New endpoints may appear.
• New enum values may appear. trust_status, renewal states and protocol identifiers are all open sets - handle unknown values instead of crashing on them. This is the single most common way clients break.
• Error message wording may change. Match on status codes.

Breaking changes

A breaking change means /v2/, with /v1/ kept running while integrators move. It will not be a silent change to /v1/.

The spec is the source of truth

The API reference on this site is generated from the OpenAPI document that the service itself is built against. If this documentation and the spec disagree, the spec wins - and that is a bug worth reporting.

The spec is OpenAPI 3.1. You can point a generator at it to produce a client, but be aware that v1 is small enough that hand-written calls are often clearer than generated code.