Skip to main content
The Dairo API is versioned in the URL path. Every data route lives under a version prefix, and today that prefix is /v1:
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:
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.
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.