Versioning
How Dolores handles breaking and non-breaking API changes.
The Dolores API uses two layers of versioning. The major version is in the URL; minor dated revisions ride on a header.
Major versions (/v1/, /v2/, …)
The current major version is /v1/. Breaking changes (renamed fields, restructured payloads, removed endpoints, changed status semantics) only ship under a new major version — /v2/, eventually.
If we ever release /v2/, /v1/ continues serving for a published sunset window (typically 12 months) before retirement. The changelog announces the timeline.
Non-breaking additions
Within /v1/, we routinely add:
- New endpoints
- New fields on existing responses
- New optional request fields
- New enum values on
code/type/status - New event types
These don't bump the version. Your code should:
- Ignore unknown response fields rather than failing schema validation.
- Match enum values from a known set and fall through to a generic handler for new values.
- Branch on
error.typefirst, thenerror.code, so a newcodefalls into the type-level fallback gracefully.
Dated minor versions (planned)
We reserve the Dolores-Version header for opting into dated minor versions:
Dolores-Version: 2026-06-01The header is reserved but inert in v1 — sending it logs your highest pinned version but doesn't change behavior. When a dated minor version ships (e.g. a default-changing fix that some clients aren't ready for), pinning will let you stay on the old behavior. We'll announce dated versions in the changelog.
What counts as breaking
Just so there's no ambiguity:
| Change | Breaking? |
|---|---|
| Adding a new field to a response | No |
| Adding a new optional request field | No |
| Adding a new endpoint | No |
Adding a new enum value (type, code, status) | No — your client should fall through unknown values |
| Adding a new event type | No |
| Adding a new HTTP header on responses | No |
| Tightening validation (rejecting input that used to be accepted) | Yes |
| Removing or renaming a field | Yes |
| Changing a field's type | Yes |
| Changing the semantics of an existing status / enum value | Yes |
| Removing an endpoint | Yes |
| Reducing rate limits | Soft-breaking — announced in changelog with notice |
Breaking changes always go to a new major version.