# Deprecation & Versioning

# 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:

1. **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.
2. **It is announced** with the date it was deprecated and the date it will be removed.
3. **Responses carry `Deprecation` and `Sunset` headers**
   ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html) and
   [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html)), plus a `Link` header with
   `rel="deprecation"` pointing here.
4. **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: **info@apis.io**.