> ## Documentation Index
> Fetch the complete documentation index at: https://alpha.developer.tomorro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Versioning

> How Tomorro versions its API and how to use versioned requests

The Tomorro Public API uses **date-based versioning** with a codename: `YYYY-MM-DD.codename`. You send the desired version in a header; the API validates it, runs the matching behavior, and returns the version and any deprecation info in the response.

## Version format

Versions follow this pattern:

* **Date**: `YYYY-MM-DD` (e.g. `2025-01-29`)
* **Codename**: lowercase label (e.g. `alpha`, `init`, ...)

Example: `2025-01-29.alpha`.

## How to specify a version

Send the `tomorro-version` header on every request:

```bash theme={null}
curl -X GET "https://api.tomorro.com/v2/members" \
  -H "x-api-key: your-api-key" \
  -H "tomorro-version: 2025-01-29.alpha"
```

If you omit `tomorro-version`, the API uses the **latest** version. We recommend setting the header explicitly so upgrades are intentional.

## Version lifecycle

Each version has a status:

| Status         | Meaning                                                                |
| -------------- | ---------------------------------------------------------------------- |
| **supported**  | Actively supported; use this for new integrations.                     |
| **deprecated** | Still works but scheduled for removal. Migrate to a supported version. |
| **sunset**     | No longer available; requests with this version return `410 Gone`.     |

When you call the API with a **deprecated** version, we still process the request but add extra response headers so you can detect and plan migration:

* **`x-api-deprecation-warning`**: Sent on every response when using a deprecated version. Contains a message (e.g. *"This version is deprecated. Please upgrade to 2025-01-29.alpha."*).
* **`sunset`**: The date when the version will be removed. After that date, the same version will return `410 Gone` instead of a successful response.

The following timeline illustrates how versions move from release through current, deprecation, and sunset, with new versions introduced at breaking changes:

```mermaid theme={null}
gantt
    title Version lifecycle timeline
    dateFormat  YYYY-MM-DD
    axisFormat  %Y-%m

    section Version:<br>jimmy-2024-01-01
    Release                     :milestone, active, rel1, 2024-01-01, 0d
    Current                     :active, cur1, 2024-01-01, 2024-06-01
    Deprecation                 :milestone, crit, dep1, 2024-06-01, 0d
    Deprecated                  :crit, depPhase1, 2024-06-01, 2024-12-01
    Sunset                      :milestone, done, sun1, 2024-12-01, 0d

    section Version:<br>renewal-2024-06-01
    Breaking Change             :milestone, crit, brk1, 2024-06-01, 0d
    Release                     :milestone, active, rel2, 2024-06-01, 0d

    Current            :active, cur2a, 2024-06-01, 2024-10-01
    Supported          :done,   cur2b, 2024-10-01, 2025-06-01

    section Version:<br>renewal-2024-10-01
    Release                     :milestone, active, rel3, 2024-10-01, 0d
    Current                     :active, cur3, 2024-10-01, 2025-06-01
```

## Strategy in short

1. **Header-based**: Version is chosen via `tomorro-version`, not the URL path.
2. **Default to latest**: Omitted header implies the current latest version.
3. **Explicit versions**: New versions are introduced when we make breaking changes; existing versions stay available until deprecated then sunset.
4. **Stable contract per version**: Once a version is released, we do not change its behavior; use a newer version for new features or breaking changes.

## Current versions

Check the **API Reference** (version selector in the docs) for the list of available versions and their OpenAPI specs. The docs and reference are split by version so you see the right request/response shapes for each.

## Best practices

<CardGroup cols={2}>
  <Card title="Pin your version" icon="thumbtack">
    Set <code>tomorro-version</code> explicitly in your client so behavior stays predictable until you choose to upgrade.
  </Card>

  <Card title="Handle deprecation" icon="bell">
    Read <code>x-api-deprecation-warning</code> and <code>sunset</code> and plan migration before a version is sunset.
  </Card>
</CardGroup>