API versioning

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 route needs no key:

curl https://api.dairo.app/v1

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

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.