---
title: "API versioning and deprecation policy"
description: "How the EveryPage API is versioned, what may change inside a version, and how deprecations and sunsets are announced in headers and docs."
canonical: "https://everypage.co/docs/developers/versioning"
plan: "free"
last-updated: "2026-09-09"
---

# API versioning and deprecation policy

The EveryPage API is versioned in the URL path. Everything documented in the [OpenAPI specification](https://everypage.co/openapi.json) lives under `/api/v1/`, and that path is the contract: an integration written against `v1` keeps working until `v1` itself is sunset, which has never happened and is not planned.

## What can change inside v1

Additive changes ship without notice and without a version bump. Treat these as normal:

- New endpoints, new optional request fields, and new query parameters.
- New fields in response objects and webhook payloads. Parse what you need and ignore the rest; never rely on key order or on an object having exactly the keys you saw yesterday.
- New values in open-ended enumerations, such as the `code` field of an [error response](https://everypage.co/docs/developers/authentication#error-responses) or a webhook event kind. Unknown values should fall through to a generic branch.
- New `Link` relations, new response headers, and tighter validation of input that was already documented as invalid.

Breaking changes do not ship inside v1. A breaking change is one that removes or renames a field, endpoint, or scope; changes a field's type or meaning; narrows what a request accepts; or changes the status code of a documented outcome. Those only arrive in a new version path, alongside `v1`, never in place of it.

## How deprecation is signalled

When a v1 endpoint, field, or the whole version is scheduled to go away, the same signal appears in three places at once:

1. **Response headers on the affected endpoint.** A `Deprecation` header ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) carrying the date the deprecation took effect, a `Sunset` header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) carrying the date the endpoint stops answering, and a `Link` header with `rel="deprecation"` pointing at the section of these docs that explains the replacement. For example:

   ```
   Deprecation: @1767225600
   Sunset: Wed, 01 Jul 2026 00:00:00 GMT
   Link: <https://everypage.co/docs/developers/versioning#deprecations>; rel="deprecation"
   ```

2. **The OpenAPI specification.** The operation or property is marked `deprecated: true` and its description names the replacement and the sunset date.
3. **This page.** The [Deprecations](https://everypage.co/docs/developers/versioning#deprecations) section below lists every active deprecation with its replacement and dates.

The notice period between the `Deprecation` date and the `Sunset` date is at least **six months**. After the sunset date the endpoint answers `410 Gone` with an [error document](https://everypage.co/docs/developers/authentication#gone) whose `hint` names the replacement. Webhook event kinds follow the same rule: a retiring kind keeps being delivered for the notice period and is listed here.

Agents can therefore rely on two mechanical checks: an endpoint with no `Deprecation` header is not going anywhere, and an endpoint with one has a `Sunset` date at least six months out.

## Deprecations

There are currently no active deprecations. Every operation in the [OpenAPI specification](https://everypage.co/openapi.json) is supported.

## Next steps

- [Authenticating with the API](https://everypage.co/docs/developers/authentication) - bearer lanes and error documents
- [API keys and scopes](https://everypage.co/docs/developers/api-keys) - credentials and what each scope allows
- [Webhooks](https://everypage.co/docs/developers/webhooks) - the event kinds this policy also covers