> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dairo.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API versioning

> How Dairo versions its API: v1 in the URL path, a version-discovery endpoint, what counts as a breaking change, and how versions retire.

The Dairo API is versioned in the URL path. Every data route lives under a version
prefix, and today that prefix is `/v1`:

```
https://api.dairo.app/v1/messages
https://api.dairo.app/v1/inboxes
https://api.dairo.app/v1/domains
```

`v1` is the current, stable version. It is the only version served today, and every
official SDK and the CLI pin `/v1` for you, so you never build the prefix by hand.

## Discover the current version

Ask the API which versions it serves. The version-discovery routes need no key:

```bash theme={null}
curl https://api.dairo.app/v1
# version-agnostic alias, same body:
curl https://api.dairo.app/version
```

```json theme={null}
{
  "version": "v1",
  "currentVersion": "v1",
  "supportedVersions": ["v1"],
  "deprecationPolicyUrl": "https://docs.dairo.app/api-versioning"
}
```

| Field                  | Meaning                                     |
| ---------------------- | ------------------------------------------- |
| `version`              | The surface the request landed on.          |
| `currentVersion`       | The version new integrations should target. |
| `supportedVersions`    | Every version the API currently serves.     |
| `deprecationPolicyUrl` | A link back to this page.                   |

`supportedVersions` is the programmatic signal to watch: a version keeps serving, and
stays in this array, until it retires.

## What counts as a breaking change

A breaking change requires a new major version (for example `/v2`):

* Removing or renaming a route, field, or enum value.
* Changing the type or shape of an existing response field.
* Making a previously optional request field required.
* Tightening validation so input that used to pass is now rejected.
* Changing the auth, scope, or error-code semantics of an existing operation.

An additive change ships in place and never bumps the version:

* A new route or operation.
* A new optional request field.
* A new response field.
* A new value in a field documented as open or extensible.

Write your integration to ignore unknown response fields, so additive changes never
break you.

## Deprecation policy

Dairo never makes a silent breaking change to a released version.

1. **New versions ship under a new prefix.** Breaking changes go out under a new path
   version, such as `/v2`. The previous version keeps working.
2. **Versions run side by side.** When `/v2` ships, `/v1` keeps serving and stays in
   `supportedVersions` until its published retirement date.
3. **Retirement is announced ahead of time.** A version is scheduled for retirement
   with a published Sunset date, announced in advance, and removed only after that date
   passes. Existing fields never change shape while a version is live.

<Note>
  A few routes sit outside the versioned data API on purpose: `/health`, `/version`,
  `/.well-known/*` (including the public agent JWKS), the branded file-link slugs (`/d/`
  downloads and `/s/` share pages), and one-click `/unsubscribe`. These are stable and
  exempt from path versioning. The MCP server and its OAuth endpoints live on their own
  host, `https://mcp.dairo.app`, outside the versioned API entirely.
</Note>