# Versioning

> How the border.bot API is versioned by path, what counts as a breaking change, and the Deprecation and Sunset headers.

Source: https://border.bot/docs/versioning
Last updated: 2026-10-09

> Documentation index: https://border.bot/llms.txt. Every page is Markdown at its URL + `.md`.


The version is the first part of the path: `https://api.border.bot/v1/classify`. The current version is **v1**. URLs without a version (`/openapi.json`, `/docs`) always serve the current one.

## What can change within a version

Only additions: new endpoints, new optional request fields, new response fields and new enum values. Write clients that ignore fields they don't know and handle enum values they haven't seen. Anything that would break a working client ships as a new version.

## Retiring a version

When a version is deprecated, its responses carry:

| Header                               | Meaning                                        |
| ------------------------------------ | ---------------------------------------------- |
| `API-Version`                        | The version that answered (on every response). |
| `Deprecation`                        | When it was deprecated (RFC 9745).             |
| `Sunset`                             | When it stops working (RFC 8594).              |
| `Link: <…>; rel="successor-version"` | The docs of the version to move to.            |

After the sunset date, the version answers `410 version_retired`. `GET https://api.border.bot/versions` lists every version with its status, dates and changes.

Each version has its own OpenAPI 3.1 document at `https://api.border.bot/v1/openapi.json`.