Skip to main content

​
Versioning

The API is versioned in the URL path. All public endpoints live under /v1. Breaking changes ship in a new version path. Within a version, changes are backward-compatible: new fields, new enum values, and new endpoints can appear at any time. Parse responses tolerantly and ignore fields you do not use.

​
Deprecation

When an endpoint or field is scheduled for removal:
  1. The OpenAPI specification marks the operation deprecated: true.
  2. Responses include a Deprecation header with the announcement date and a Sunset header with the removal date (RFC 8594 and the HTTP Deprecation header draft).
  3. The removal is announced in product updates with a migration window of at least 90 days.
Integrate against the current version and watch for the Deprecation header. Agents can rely on the header pair to detect a sunset before it takes effect.

​
Rate limits

Every v1 response carries rate-limit headers:
  • RateLimit-Limit: the request ceiling for the current window.
  • RateLimit-Remaining: requests left in the current window.
  • RateLimit-Reset: Unix time (seconds since epoch) at which the window resets.
A throttled request returns HTTP 429 with a Retry-After header. Wait at least that many seconds before you retry. The default ceiling is 600 requests per 60 seconds per API key; a key can carry its own override.