Skip to main content

​
URL-based versioning

The API version is part of the URL path. The current version is v1:
Service endpoints (/ and /health) have no version prefix — they are always unversioned. There is no header-based version pinning. The version in the path is the version you get.
The v1 API is in early access. While the surface stabilizes, an occasional breaking change may still ship in place — each one is recorded in the Changelog with a migration note. The guarantees below describe the stability policy that applies in full once v1 is generally available.

​
What stays stable within a version

Breaking changes never ship in place. When a change would break existing clients, it goes behind a new path prefix (for example, a future /v2). Until then, the /v1 surface is stable: the same request produces the same shape of response.

​
Breaking changes — require a new version

These changes would move to a new path prefix before rolling out:

​
Additive changes — safe within the current version

These changes ship under /v1 without a version bump. Existing clients keep working as long as they ignore unknown fields:
  • New endpoints
  • New optional request fields or query parameters
  • New response fields
  • New error codes (on conditions that couldn’t be reached before)
  • Loosened validation (accepting input previously rejected)
  • Bug fixes that bring behavior in line with documented behavior
Write forward-compatible clients: ignore unknown fields in responses, treat unknown error.code values as generic errors (fall back to the HTTP status class), and avoid exhaustive branching on enum values. Clients that follow this pattern are unaffected by additive changes.

​
Deprecation and sunset

When a new major version ships, the previous version remains available for at least 12 months from the new version’s general availability date. During the deprecation window:
  • Every response from the deprecated version includes Deprecation: true and Sunset: <date> headers. Check for these headers in your integration to get early notice.
  • The API key owner email on file receives two notices: one at the deprecation announcement and one at least one month before the sunset date.
At sunset, deprecated endpoints return 410 Gone with error code version_sunset. This state lasts at least 30 days before the endpoints are removed entirely. The same window applies to individual endpoints or fields deprecated within a major version — at least 12 months for endpoints, at least 6 months for fields.

​
Next steps

Error handling

Error envelope shape, stable error codes, and how to branch on them safely.

API reference

Full reference for every endpoint in the current version.