---
title: Versioning
description: The current API version, the X-API-Version response header, and our compatibility policy.
---

# Versioning

The API is served under a single stable major prefix, `/api/v1`, and
stamps a date-based version on **every response** so clients can detect
drift:

```http
X-API-Version: 2026-04-24
```

You don't need to send a version header — there is one active version
and the server stamps it on the way out.

---

## Compatibility policy

We add functionality without breaking existing integrations:

**Non-breaking (rolled into the current version):**

- Adding a new optional field to a response
- Adding a new optional parameter to a request
- Adding a new endpoint or webhook event type
- Adding a new error `code`

**Breaking (would ship under a new dated version with advance notice):**

- Removing or renaming a response field
- Changing a field's type
- Tightening a validation rule
- Changing default behaviour when an optional parameter is omitted

Build clients defensively: ignore unknown fields, switch on the error
`code` (not `message`), and don't assume an enum is closed unless this
documentation says so.

---

## By transport

- **REST** — `X-API-Version` stamped on every response.
- **MCP** — tools are generated from the same REST surface; they track
  the current version.
- **Webhooks** — the event envelope carries `id`, `type`, `created_at`,
  and `data` (see [Webhooks](./webhooks.md)). Branch on `type`.

---

## See also

- [Changelog](./changelog.md) — chronological API changes.
- [Errors](./errors.md) — the stable error-code catalog.
- [SDKs](./sdks.md) — using the REST API today.