Versioning & deprecation

The major version lives in the URL path (/v1/). Within a major version we make additive changes only — your integration keeps working.

What we may change within v1 (non-breaking)

• Adding new endpoints, optional parameters, or response fields
• Adding new error code values
• Adding new response headers
• Increasing limits or page-size maximums

Build tolerant clients: ignore unknown response fields and treat unknown error codes as non-retryable.

What we will never change within v1 (breaking)

• Removing or renaming fields, endpoints or parameters
• Changing a field's type or semantics
• Changing the meaning of an existing error code
• Tightening validation in a way that rejects previously valid requests

Breaking changes ship as a new major version (/v2/) running alongside /v1/.

What null means

A null is always a statement about the data, never about our ability to retrieve it. It means the value does not exist for that resource: this word has no recorded etymology, this account has no external link, this result carries no publication date.

It never means "we could not fetch this part". If we cannot assemble a complete response, the request fails with a retryable error instead of returning one with fields nulled out. A degraded answer that looks like a normal one is worse than an error, because only the error tells you to try again — so you can treat every null as a fact and build on it.

Changes outside our control

Our data reflects what is publicly available in the world, and the world sometimes changes: a data point that used to be public can be restricted, hidden or discontinued at its origin. When the underlying information ceases to exist publicly, no API can keep providing it — this is the one category of change the guarantees above cannot cover. In that event:

1. Affected fields keep their place in the schema and return null — consistent with the rule above, because the value genuinely no longer exists. This is why fields that depend on external availability are nullable by design.
2. We announce the change in the changelog — and by email when impact is material — as soon as practicable, ahead of time whenever the change is known in advance.
3. Responses may carry a meta.warnings entry while the change rolls out.
4. If the field is later removed entirely, the removal follows the standard deprecation process below.

Deprecation policy

The contract covers fields, not just endpoints — a response that quietly loses a field is as breaking as an endpoint that disappears, and is harder to notice.

Endpoints and versions

1. The deprecation is announced in the changelog and by email to affected accounts, at least 90 days before removal.
2. Deprecated endpoints respond with a Sunset header carrying the removal date and a Link to the migration guide.
3. During the window, the endpoint keeps working normally. After the sunset date it returns 404 ENDPOINT_NOT_FOUND.

Fields

A field is retired on the same terms, with the same 90-day notice in the changelog and by email. Throughout the window it keeps returning the value it documents.

What will not happen: a field is never removed without notice, and never starts returning null in place of a value it used to carry as a way of retiring it quietly. Because null is a statement about the data, using it to phase a field out would corrupt the meaning of every other null in the response.

Staying informed

Watch the changelog for all platform changes. Service incidents and maintenance are published separately on the status page.