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:

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). Branch on type.

---

See also

• Changelog — chronological API changes.
• Errors — the stable error-code catalog.
• SDKs — using the REST API today.