# REST API: version

Adresse: https://docs.athaus.ai/en/api/v1/fassungen

> The version is the path v1. The Athaus-Version header, the release, and what is never a break.

Type: Reference
Last updated: 2026-11-16

The version of the API is its path: `v1`. Inside `v1` changes only add: new operations, new optional members, new values where the docs call a list open. A client ignores members it does not know. A change that breaks existing clients makes `/v2`, and `/v1` then keeps running for at least 12 months next to it.

## The Athaus-Version header [#the-athaus-version-header]

You do not have to send a header, and it tells you nothing you need. Every response names `v1` in the header `Athaus-Version` and in `GET /v1/me` as `apiVersion`. If you send it, we accept `v1` and `1`.

```bash
curl https://api.athaus.ai/v1/me   -H "Authorization: Bearer ath_live_..."   -H "Athaus-Version: v1"
```

Every other value is a `400` with `api_version_unsupported`, so a client that asks for something unknown is told so. A key depends on no version.

## The release [#the-release]

`v1` is the version, `1.1` is the release: every response to a call with a valid key names it in the header `Athaus-Release` and in `info.version` of the OpenAPI document. It counts the additions inside `v1` (`1.0`, `1.1`, `1.2`) and is only a name: no request can select a release, and nothing behaves differently by it. The releases are listed with their dates in [What's new](/en/neuigkeiten). A release is cut with one entry there and one bump of the constant `API_RELEASE`, in the pull request that ships the additions or in a small one after a batch.

## What a break is [#what-a-break-is]

A member is removed or changes its meaning, a value of an enumeration is removed, a path disappears. That gets a new version. Until there is a break, there is only the one.

## What is no break [#kein-bruch]

This can happen at any time without a new version. Build your client to tolerate it: ignore unknown members, handle unknown values of an enumeration, do not read the cursor or the page token.

* New resources and new operations.
* New optional request parameters.
* New fields in a response object.
* New values in an enumeration. Clients must handle values they do not know.
* New event types.
* New error codes and new error types. Branch on a known code and treat all others by their HTTP status.
* A change of the human-readable error message.
* A change of the order of keys in an object.
* A change of the content or the length of a cursor. A cursor is opaque.
* A change of the length or the character set of an object ID.
* New headers in a response.

## Deprecation [#deprecation]

The promise, from this version on: what goes away is deprecated first, at least 12 months before it ends. Responses then carry the headers `Deprecation` and `Sunset`, which name both dates, and the [reference](/en/api/v1/referenz) marks the element as deprecated. A deadline is never shortened. Nothing is deprecated today.
