API versioning
The/v2 base URL is permanent. Behavior is versioned by release date — when we ship a breaking change, it goes out as a new dated version, and your integration keeps receiving the version it was built against until you choose to upgrade.
How to pin a version
Send theX-API-Version header with a release date (YYYY-MM-DD):
- Omit the header and you get the latest release. Good for trying things out; pin a date before you ship.
- Every response echoes the resolved version back in the
X-API-Versionresponse header, so you can confirm exactly which version served the request.
We recommend pinning an explicit
X-API-Version in production. Without it, your integration silently moves to the latest release whenever we publish one, which may include breaking changes.Unknown or malformed versions
A version that isn’t a published release — a typo, a future date, or a retired version — is rejected rather than silently changed:400 Bad Request. It’s deliberate: a mistyped version should fail loudly, never upgrade you by accident.
How older versions keep working
Internally the API always runs the latest shape. When you pin an older release, the response is transformed back to the shape that release promised (and your request body is upgraded forward), so older integrations see no change in their contract. You only adopt new fields and behavior when you move your pinned date forward.Discover versions programmatically
GET /v2/versions returns the supported releases — no authentication required, so your setup or CI can check before pinning:
Released versions
Use the version switcher at the top of these docs to read the reference for a specific release. Each version’s API reference reflects exactly the schema that version serves. New releases and their changes are recorded in the changelog.