---
title: API versioning
description: The /v1/ convention — what the prefix means, what stability it promises, and how future versions will work.
sidebar:
  label: Versioning
  order: 6
---

## 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.

:::note[The spec is the contract]
The authoritative definition of `v1` — exact paths, schemas, enums, error
taxonomy — is the generated OpenAPI 3.1 document rendered in the
[API reference](/reference). This page describes the convention, not the
contract details.
:::

## 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.