API versioning
The /v1/ convention — what the prefix means, what stability it promises, and how future versions will work.
The /v1/ convention
Every canonical path lives under /v1/:
/v1/sessions
/v1/sessions/{session_id}
/v1/sessions/{session_id}/end
/v1/sessions/{session_id}/client-token
/v1/api-keys
/v1/api-keys/{key_id}The prefix is the stability promise: within v1, paths, request/response
schemas, and error codes only change additively — new optional fields, new
error codes, new endpoints. Breaking changes require a new version prefix, not
a change to v1.
What stability means here
| Change | Within /v1/ |
|---|---|
| New optional request field | Allowed (additive) |
| New response field | Allowed (additive) |
| New error code | Allowed (additive) |
| Removing/renaming a field | Not allowed — new version |
| Changing a path or method | Not allowed — new version |
| Changing a field’s type/semantics | Not allowed — new version |
When a future version arrives
Future major versions will mount side by side (/v2/, …) rather than
replacing /v1/:
/v1/keeps working through a documented deprecation window.- Version-specific docs will live under explicit URL prefixes
(
/v1/,/v2/) with a version selector on this site. - The generated API reference is versioned with the spec — each version’s reference is generated from that version’s OpenAPI document.
Non-canonical legacy routes are not a version
Bridge/internal routes inherited from pre-V0 development (alternate start, status, token-refresh aliases) are not part of any version contract. They are transitional, marked as non-canonical where you may encounter them in these docs, and are scheduled for removal — never build against them.