> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API versioning & deprecation

> How Orbit versions its REST API — dated versions, pinning one with the X-Api-Version request header, and the deprecation → sunset lifecycle.

# API versioning & deprecation

Orbit's REST API is versioned by date (e.g. `2026-03-01`). Every response
carries the version it was served as in the `X-API-Version` header, so an
integration can always tell which version answered.

## Pinning a version

Send the `X-Api-Version` (or `Api-Version`) request header to pin a dated
version per request — the same model as Stripe's `Stripe-Version` header. No
request header means the current version; there is no account-level pin to
configure, so you can flip a pin at any time by changing a header.

If you pin a version that is not in the registry — a typo or a stale pin —
the request succeeds and is served by the current version. The response adds
an `X-Api-Version-Warning` header naming the pin it did not recognize, instead
of failing with a 4xx from a response hook.

## Lifecycle

Each dated version moves through three stages:

| Status | Meaning |
| - | - |
| `current` | The version served when no pin is sent. Exactly one version is current. |
| `deprecated` | Still serves requests, but a replacement exists and migration should be scheduled. |
| `sunset` | Past its retirement date — requests pinning it are served by the current version. |

Deprecated versions keep working until their sunset date; only after that date
do pinned requests fall through to the current version. This window — at least
six months — is the migration runway.

A new dated version is cut only for breaking changes. Additive, backward-
compatible changes (new endpoints, new optional fields, new enum values) land
on the current version without a new date.

## Discovering the registry

`GET /developer/api-versions` lists every dated version with its status,
released date, deprecation date, and sunset date, plus the `migration_url`
linking back to this page. Integrations that need to schedule migrations
should poll this endpoint rather than hard-coding dates.

## Deprecation headers

When your request resolves to a deprecated or sunset version, the response
adds standard `Deprecation` and `Sunset` headers (RFC 8594) plus a
`Link: <…>; rel="deprecation"` header pointing here, and an
`X-Api-Deprecation-Info` header naming the sunset date and the version to
migrate to. Client SDKs surface the same information as a non-fatal warning.

## Response example

```
X-API-Version: 2025-01-01
Deprecation: true
Sunset: Sat, 01 Nov 2026 00:00:00 GMT
Link: <https://docs.orbit.devotel.io/api-reference/versioning>; rel="deprecation"; type="text/html"
X-Api-Deprecation-Info: API version 2025-01-01 is deprecated. It will stop being served after 2026-11-01. Migrate to 2026-03-01: https://docs.orbit.devotel.io/api-reference/versioning
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.