# REST-API: Testmodus

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

> Ein Test-Key arbeitet in einem Testbüro mit erfundenen Daten. Nichts verlässt Athaus außer Webhooks an deine eigenen Adressen.

Typ: Anleitung
Zuletzt aktualisiert: 2026-11-16

Mit einem Test-Key baust du gegen `/v1`, ohne ein echtes Büro, einen Anfragenden oder ein Portal zu berühren. Er sieht aus wie ein Live-Key und heißt `ath_test_...`.

```http
Authorization: Bearer ath_test_...
```

## Das Testbüro [#das-testbüro]

Jedes Büro hat höchstens ein Testbüro: eine eigene Organisation mit eigenen Daten, die auf das echte Büro zeigt. Es entsteht mit dem ersten Test-Key. Ein Test-Key führt immer ins Testbüro, nie ins echte, und das echte Büro sieht nichts davon.

Ein neues Testbüro beginnt mit erfundenen Daten:

| Was                                                  | Wie viele |
| ---------------------------------------------------- | --------- |
| Inserate (Wohnung zum Kauf, Wohnung zur Miete, Haus) | 3         |
| Kontakte                                             | 5         |
| Anfragen                                             | 2         |
| Besichtigung                                         | 1         |
| Datei (ein kleines erzeugtes Bild)                   | 1         |

Die Straßen heißen Musterstraße, die Adressen enden auf `example.com`. `GET /v1/me` liefert `key.mode` als `test` und die Id des Testbüros.

## Einen Test-Key anlegen [#einen-test-key-anlegen]

Wähle unter [Einstellungen, API-Keys](https://app.athaus.ai/einstellungen/api-keys) beim **Key-Typ** *Test*. Scopes und die Einschränkung je Ressource funktionieren wie bei einem Live-Key, ebenso die Regel, wer Keys anlegen darf. Der Tarif des echten Büros entscheidet: Pro und Scale gehen, in Basic antwortet die API [`plan_required`](/api/errors#plan_required).

Ein Test-Key arbeitet nur bei `/v1`, nicht am MCP-Server und nicht in der App. Er zählt nicht gegen die Anbindungen deines Tarifs, aber ein Büro hat höchstens 10 gültige Test-Keys gleichzeitig: Der elfte wird beim Anlegen in der App mit [`test_key_limit_erreicht`](/api/fehlercodes#test_key_limit_erreicht) beantwortet. Das Testbüro ist in der App nicht sichtbar.

## Nichts verlässt Athaus [#nichts-verlässt-athaus]

Im Testbüro geht keine E-Mail, keine SMS und keine andere Nachricht hinaus. Kein Portal bekommt etwas, kein angebundenes CRM wird beschrieben, kein Inserat wird öffentlich. Auch läuft kein KI-Modell.

Eine Nachricht, die du an eine Anfrage schickst, steht dann im Verlauf als gesendet, mit dem Vermerk, dass sie im Testmodus nicht zugestellt wurde. Der Vorschlag endet als `executed`.

Webhooks laufen weiter: Die Endpunkte eines Test-Keys gehören zum Testbüro, bekommen seine Ereignisse und werden genauso signiert, du kannst also deinen Empfänger testen. Fällt ein Endpunkt dauerhaft aus, wird er wie jeder andere abgeschaltet (`disabledReason`, `disabledAt`); dazu geht keine E-Mail hinaus.

## Ereignisse unterscheiden [#ereignisse-unterscheiden]

Jedes [Ereignis](/api/v1/ereignisse) trägt `livemode`: `true` für das echte Büro, `false` für das Testbüro. Ein Vorschlag trägt dasselbe Mitglied.

```json
{ "object": "event", "type": "proposal.pending", "livemode": false }
```

## Vorschläge über die API entscheiden [#vorschläge-über-die-api-entscheiden]

In einem echten Büro sagt eine Person in der App Ja oder Nein, oder ein Key mit dem Scope `decide`. Im Testbüro ist niemand, darum gibt es zwei Pfade, die ein Test-Key ohne diesen Scope nutzt:

| Pfad                              | Wirkung                                                                       |
| --------------------------------- | ----------------------------------------------------------------------------- |
| `POST /v1/proposals/{id}/approve` | Ja: Die Nachricht steht im Verlauf als gesendet, der Vorschlag ist `executed` |
| `POST /v1/proposals/{id}/reject`  | Nein: Nichts wird gesendet, der Vorschlag ist `rejected`                      |

So spielst du "`202` mit einem Vorschlag, dann Ja" ohne die App durch ([Was das Büro verlässt](/api/v1/hinausgehen)). Ein Live-Key braucht dafür den Scope `decide`, sonst `403` ([Ohne Person entscheiden](/api/v1/hinausgehen#decide)). Auch hier siehst du nur die Vorschläge deines eigenen Keys.

## Zurücksetzen [#zurücksetzen]

`POST /v1/test/reset` stellt die Beispieldaten wieder her. Alles andere im Testbüro verschwindet, auch die alten Ereignisse. Die Beispieldaten selbst melden keine Ereignisse: Dein Empfänger bekommt keine Flut von `created`-Ereignissen, nur was du danach anlegst oder änderst. Webhook-Endpunkte und Keys bleiben, und das Testbüro behält seine Id. Der Key braucht Schreibzugriff auf alle Ressourcen. Mit einem Live-Key: `404`.

## Grenzen [#grenzen]

Es gelten dieselben [Grenzen](/api/v1/limits) wie bei Live-Keys. Das Testbüro ist zusätzlich gedeckelt, damit es kein Speicher wird: 200 Inserate, 1.000 Kontakte und 100 MB Dateien. Darüber antwortet die API mit `403` und [`test_office_full`](/api/errors#test_office_full). Zurücksetzen schafft wieder Platz.

## Was schiefgehen kann [#was-schiefgehen-kann]

| Status | Code                                               | Ursache                                               |
| ------ | -------------------------------------------------- | ----------------------------------------------------- |
| `403`  | [`test_office_full`](/api/errors#test_office_full) | das Testbüro hat seine Grenze erreicht                |
| `409`  | [`test_office_busy`](/api/errors#test_office_busy) | das Testbüro wird gerade aufgebaut oder zurückgesetzt |
| `403`  | [`plan_required`](/api/errors#plan_required)       | der Tarif des echten Büros hat keinen API-Zugang      |
| `404`  | [`not_found`](/api/errors#not_found)               | Zurücksetzen oder Entscheiden mit einem Live-Key      |
