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

# Versioning

> Pin an API version per Auth Client or per request.

The `X-API-Version` header controls the request and response shapes your code sees. Each Auth Client has a default version, used when the header isn't sent. New Auth Clients default to the latest stable release.

Breaking changes only ship in a new version, so existing integrations keep working until you opt in. Additive changes (new response fields, new endpoints) can land in existing versions, so build your client to ignore fields it does not recognize. Every response echoes the version it was processed with:

```http theme={null}
HTTP/1.1 200 OK
X-API-Version: 2026-01-29.edison
```

## Upgrade an Auth Client

<Steps>
  <Step title="Review the changelog">
    Check what changed between your current version and the target in the [Changelog](/api-references/changelog).
  </Step>

  <Step title="Test against your existing traffic">
    Send the target version as `X-API-Version` to override the Auth Client's default on a per-request basis. Confirm everything still works before changing the default.

    ```bash theme={null}
    curl https://api.nomos.energy/subscriptions \
      -H "Authorization: Bearer ${ACCESS_TOKEN}" \
      -H "X-API-Version: 2026-01-29.edison"
    ```
  </Step>

  <Step title="Switch the default in the dashboard">
    In the Nomos dashboard, open **Developer**, edit the Auth Client, pick the new version, and save. Future tokens minted by that client use the new version. Tokens issued earlier stay on the previous version until they expire (see [Authentication](/api-references/authentication) for token lifetime).
  </Step>
</Steps>

## Available versions

| Version             | Status                 |
| ------------------- | ---------------------- |
| `2026-01-29.edison` | Latest stable          |
| `2025-12-16.batman` | Previous release       |
| `2025-12-01.chucky` | Initial stable release |

See the [Changelog](/api-references/changelog) for what changed in each release.