Versioning and Deprecation
How the TheirStack API versions its endpoints, what counts as a breaking change, and the notice you get before anything is removed.
The TheirStack API is versioned in the URL path (/v0/, /v1/). A version never changes its contract once it is published, so an integration you build today keeps working. New capabilities arrive as additions you can adopt when you want, and anything we retire comes with notice and a documented replacement.
What counts as a breaking change
A breaking change is one that can stop a well-behaved integration from working. These only ship in a new version path, never on an existing one. They include:
- Removing an endpoint, a field, or a query parameter.
- Renaming a field or a parameter.
- Changing the type or meaning of an existing field.
- Making an optional parameter required, or adding a new required parameter.
- Removing a value from an enum, or narrowing what a filter accepts.
A non-breaking change adds to the API without changing what is already there. These ship on the current version without notice, at any time:
- New endpoints.
- New fields in a response.
- New optional query parameters.
- New values in an enum.
Build for non-breaking changes
Expect additive changes. An integration that reads only the fields it needs and ignores the ones it does not will not break when we add more.
- Ignore unknown fields in responses instead of failing on them.
- Do not assume an enum lists every value it ever will; handle values you do not recognize.
- Do not depend on the order of fields, or on a response containing only the fields you have seen before.
The deprecation window
When we deprecate a version or an endpoint, it stays available for at least 3 months before we remove it. During that window the endpoint keeps working exactly as before. We announce a deprecation in three ways at once:
- An email to the active API users of the affected endpoint.
- A product update in the public changelog.
- Response headers on the endpoint itself.
Smaller changes that are not an endpoint or version removal, such as tightening what a filter accepts, may use a shorter, separately announced window. We carry those with the same response headers, and where we can we give existing callers a stated period on the old behavior before the change applies to them.
How deprecations are marked
A deprecated operation is flagged deprecated: true in the OpenAPI specification, which renders it struck through in this reference, and its description names the endpoint to move to. The specification is the source of truth for what is deprecated right now.
Deprecated endpoints also return the RFC 8594 headers so your client can detect the state without reading the docs:
Deprecation: when the endpoint became deprecated.Sunset: the date on or after which it may stop working. Present once a removal date is set.
Deprecation: @1793750400
Sunset: Tue, 08 Dec 2026 00:00:00 GMTLog these headers and alert on them. A Sunset date is your signal to migrate before that day.
Currently deprecated endpoints
Both /v0/ and /v1/ are live. Most /v0/ endpoints are current and have no /v1/ equivalent; a few have been superseded and are marked deprecated. The one you are most likely to meet:
POST /v0/company_lists/{list_id}/add_companies— usePOST /v1/company_lists/{list_id}/add_companiesinstead. The v1 endpoint takescompany_idsonly, and its400error names the IDs it could not find.
For the full, current list, look for the deprecated flag in the OpenAPI specification.
Questions
Contact support if you are unsure whether a change affects you, or if you need more time to migrate off a deprecated endpoint.
How is this guide?
Last updated on
Authentication
Learn how to set up TheirStack API authentication with Bearer token API keys — create, manage, and revoke keys directly from your account settings.
Pagination
Learn how to paginate TheirStack API responses with page-based and offset-based methods, including tips for faster queries on GET and POST endpoints.
