# Versioning

> What versioning means for the up4 API today: one URL version, what X-API-Version and a key’s api_version do, and where breaking changes are announced.

Source: https://upfour.io/docs/api/versioning

The API has one version, `/v1`. Changes land inside it, and the [changelog](https://upfour.io/docs/api/changelog.md) records each one, including the ones that can break a client.

## What the API does today

| Topic | Behavior |
| --- | --- |
| **URL version** | Every operation is served under `/v1`. There is no other version and no `/v2`. |
| **`X-API-Version` request header** | Accepted. Any non-empty value marks the request as a public API request, which gives it the `data` envelope and, on `GET /monitors`, cursor pagination. The value itself is not read. |
| **`api_version` of a key** | Each key stores one, `2026-05-07` by default. `GET /me` returns it. No behavior changes with it. |
| **`Deprecation` and `Sunset` headers** | The API sends neither. |

```bash
curl -s https://app.upfour.io/v1/me \
  -H "Authorization: Bearer $UP4_API_KEY" \
  -H "X-API-Version: 2026-05-07"
```

The call above behaves exactly like one without the header, because a request made with an API key already gets the public API behavior.

## How changes reach you

The changelog labels every change to the contract as **breaking**, **added**, **changed**, **deprecated** or **documented**, and has a “Breaking only” filter. It is generated from the history of the OpenAPI file. Watch it, or the [OpenAPI file](https://upfour.io/api/openapi.json) itself, for the operations you use.

The stated intention is that a breaking change gets its own version, `/v2`, with 12 months of parallel support and `Deprecation` and `Sunset` headers. That is an intention, not behavior you can test: there is no `/v2` and no header today, and the changelog shows breaking changes that were made inside `/v1`. Plan for the changelog, not for a header.

## Write a tolerant client

- Ignore response fields you do not know; new ones appear as **added**.
- Do not depend on the order of keys, or of `scopes` in `GET /me`.
- Branch on `error.code`, not on `error.message`. See [responses](https://upfour.io/docs/api/responses.md).
- Cover the operations you use with tests. A changed required scope is labeled breaking in the changelog.

## Common mistakes

- Sending `X-API-Version` to pin an old behavior. It pins nothing.
- Changing a key’s `api_version` to get a different response. There is no such effect.
- Waiting for a `Sunset` header before checking for removals. Read the changelog.
- Building against `/v2` paths. They do not exist.