The HTTP API changes under a date-based version contract. Clients can follow the current version automatically or pin the version they were written against.

Version requests

Every response under /api carries API-Version. Omit the request header to receive the current version, or send the value advertised by the deployment:

API-Version: 2026-09-10

An unknown version is refused with 400 unsupported_version; it is not silently served by a different contract.

Deprecation

A breaking contract change receives a new date. A previous version remains available for at least ninety days after deprecation. Responses pinned to that version carry:

Deprecation with the structured-field date it became deprecated;
Sunset with the final date it answers;
Link with rel="deprecation" pointing to this page.

Clients should watch for Deprecation so a future notice is visible without a code change.

Limits and errors

API responses name the rate-limit policy they passed under. A refused request returns 429, Retry-After and rate-limit state. Slow down for the named interval instead of guessing a delay.

Errors use the ApiError shape in OpenAPI: a short error code and, when useful, error_description. OAuth endpoints use their standard OAuth error codes. A missing token returns 401 with authorization discovery in WWW-Authenticate; an authorized token without the needed scope returns 403 insufficient_scope.

Read the developer page for discovery URLs and authentication.