Deprecation & versioning

Versioning

The API is versioned in the path: https://apis.io/api/v1. The version changes only for a breaking change. Everything else — new endpoints, new response fields, new optional query parameters, new tiers — ships into /v1 without a version bump, so clients should ignore response fields they do not recognise rather than failing on them.

What counts as breaking

Removing an endpoint, or a field from a response.
Renaming a field, or changing its type.
Making an optional request parameter required.
Narrowing an enum, or changing the meaning of an existing value.
Changing the default page size, or the shape of the paging envelope.
Moving a resource from an open tier to a gated one.

Adding a field, adding an endpoint, adding an optional parameter, widening an enum, raising a rate limit, or improving a description is not breaking.

Deprecation

When something is going away:

It is marked in the contract with deprecated: true — the machine-readable signal, visible to an agent or a generated client without reading this page.
It is announced with the date it was deprecated and the date it will be removed.
Responses carry Deprecation and Sunset headers (RFC 9745 and RFC 8594), plus a Link header with rel="deprecation" pointing here.
The replacement is named. Nothing is deprecated without somewhere to go.

Notice period

Change	Minimum notice
Deprecating an endpoint or field in `/v1`	6 months before removal
Retiring an entire API version	12 months , with `/v1` and `/v2` served in parallel
Security-forced removal	As much as is safe — announced immediately, with the reason

The only change made without notice is one required to close a security or privacy problem, and it is announced the moment it ships rather than before it.

Server host changes

The base URL is https://apis.io/api/v1. An earlier set of published contracts declared search-api.apis.io, a host that has no DNS record; those contracts were corrected on 2026-08-21 and every one was re-verified callable against the current base. If you integrated against the old host, it never resolved — move to https://apis.io/api/v1.

Questions about a deprecation: [email protected].

Last modified on August 21, 2026

Security