# REST-API: Version

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

> Die Version ist der Pfad v1. Der Kopf Athaus-Version, die Ausgabe und was nie ein Bruch ist.

Typ: Referenz
Zuletzt aktualisiert: 2026-11-16

Die Version der API ist ihr Pfad: `v1`. Innerhalb von `v1` kommt nur etwas hinzu: neue Operationen, neue optionale Mitglieder, neue Werte dort, wo die Doku eine Liste offen nennt. Ein Client ignoriert Mitglieder, die er nicht kennt. Eine Änderung, die bestehende Clients bricht, bekommt `/v2`, und `/v1` läuft danach noch mindestens 12 Monate daneben.

## Der Kopf Athaus-Version [#der-kopf-athaus-version]

Du musst keinen Kopf senden, und er sagt dir nichts, was du brauchst. Jede Antwort nennt `v1` im Kopf `Athaus-Version` und in `GET /v1/me` als `apiVersion`. Wenn du ihn sendest, nehmen wir `v1` und `1` an.

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

Jeder andere Wert ist ein `400` mit `api_version_unsupported`, damit ein Client, der etwas Unbekanntes verlangt, es erfährt. Ein Key hängt an keiner Version.

## Das Release [#das-release]

`v1` ist die Version, `1.1` ist das Release: Jede Antwort auf einen Aufruf mit gültigem Key nennt es im Kopf `Athaus-Release` und im Feld `info.version` des OpenAPI-Dokuments. Es zählt die Ergänzungen innerhalb von `v1` (`1.0`, `1.1`, `1.2`) und ist nur ein Name: Keine Anfrage kann ein Release wählen, und nichts verhält sich nach ihm anders. Die Releases stehen mit Datum in den [Neuigkeiten](/neuigkeiten). Ein Release entsteht mit einem Eintrag dort und einer Erhöhung der Konstante `API_RELEASE`, in dem Pull Request, der die Ergänzungen ausliefert, oder in einem kleinen danach.

## Was ein Bruch ist [#was-ein-bruch-ist]

Ein Mitglied fällt weg oder ändert seine Bedeutung, ein Wert einer Aufzählung fällt weg, ein Pfad verschwindet. Dafür gibt es eine neue Version, `/v2`. Bis es einen Bruch gibt, gibt es nur `v1`.

## Was kein Bruch ist [#kein-bruch]

Das kann jederzeit ohne neue Version geschehen. Bau deinen Client so, dass er es verträgt: unbekannte Mitglieder ignorieren, unbekannte Werte einer Aufzählung behandeln, den Cursor und das Page Token nicht lesen.

* Neue Ressourcen und neue Operationen.
* Neue optionale Parameter in einer Anfrage.
* Neue Felder in einem Antwortobjekt.
* Neue Werte in einer Aufzählung. Clients müssen Werte behandeln, die sie nicht kennen.
* Neue Ereignisarten.
* Neue Fehlercodes und neue Fehlerarten. Verzweige auf einen bekannten Code und behandle alle anderen nach ihrem HTTP-Status.
* Eine Änderung des Fehlertexts für Menschen.
* Eine andere Reihenfolge der Schlüssel in einem Objekt.
* Eine Änderung von Inhalt oder Länge eines Cursors. Ein Cursor ist undurchsichtig.
* Eine Änderung von Länge oder Zeichensatz einer Objektkennung.
* Neue Köpfe in einer Antwort.

## Abkündigung [#abkündigung]

Zugesagt ist ab dieser Version: Was wegfällt, wird zuerst abgekündigt, mindestens 12 Monate vor dem Ende. Die Antworten tragen dann die Köpfe `Deprecation` und `Sunset`, die beide Daten nennen, und die [Referenz](/api/v1/referenz) markiert das Element als abgekündigt. Eine Frist wird nie verkürzt. Heute ist nichts abgekündigt.
