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/.

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 but return null (which 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.

Build clients that tolerate null in nullable fields — it is the contract's way of saying "this information is no longer available", not an error.

Deprecation policy

When we retire an endpoint or version:

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.

Staying informed

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