API versioning and deprecation

Last updated 4 October 2026.

The API is described at /openapi.json. Live capabilities are listed at /capabilities.json.

Versions

Paths carry a major version (/api/v1/). Every response carries an X-Dusk-State-Version header. Within a major version we only add: new fields, new endpoints and new optional parameters. Clients should ignore fields they do not recognise.

Breaking changes

A breaking change ships under a new major version. The previous version stays available for at least 90 days after the new one is published. During that time its responses carry Deprecation and Sunset headers and a Link to the replacement.

Records

Records carry their own version and as_of date. A corrected statement is marked superseded rather than silently replaced.