Conductor Deck API versioning & deprecation policy
Agents avoid integrating against a surface that can change without warning. This is what Conductor Deck commits to, stated precisely enough to hold us to it.
The current version is v1, served under /api/v1. Every response echoes X-API-Version.
What can change, and what cannot
- Additive changes ship without notice
- New fields may be added to a response without a version bump. Parse defensively: ignore fields you do not recognise.
- Breaking changes ship as a new version
- A breaking change ships as a new version prefix (/api/v2). The previous version keeps working; it is never changed in place.
- Removals get at least 180 days
- A deprecated endpoint answers with a Deprecation header, a Sunset header carrying the removal date, and a Link rel="deprecation" pointing at the migration notes. No endpoint is deprecated today, so no endpoint currently sends them.
How a deprecation is signalled
On the affected endpoint's own responses, so a client discovers it by calling the endpoint rather than by reading this page on a schedule.
| Header | Specification | Carries |
|---|---|---|
Deprecation | RFC 9745 | The date the deprecation took effect. |
Sunset | RFC 8594 | The date the endpoint stops answering. |
Link; rel="deprecation" | RFC 8288 | The migration notes for that endpoint. |
Nothing is deprecated today, so no endpoint currently sends any of them. The machine-readable copy of that fact is the empty currently_deprecated array in openapi.json.
Read this policy as data
The same commitments, for a client that would rather parse than read:
GET /api— theversioningobject, alongside every endpoint and both authentication options. No credential required./openapi.json—info.x-deprecation-policyandinfo.x-api-versioning.
Questions about a migration: support@conductordeck.com