# REST API: test mode

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

> A test key works in a test office with invented data. Nothing leaves Athaus except webhooks to your own addresses.

Type: Guide
Last updated: 2026-11-16

With a test key you build against `/v1` without touching a real office, an inquirer or a portal. It looks like a live key and is called `ath_test_...`.

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

## The test office [#the-test-office]

Every office has at most one test office: its own organisation with its own data, pointing at the real office. It is created with the first test key. A test key always resolves to the test office, never the real one, and the real office sees none of it.

A new test office starts with invented data:

| What                                                     | How many |
| -------------------------------------------------------- | -------- |
| Listings (apartment for sale, apartment for rent, house) | 3        |
| Contacts                                                 | 5        |
| Inquiries                                                | 2        |
| Viewing                                                  | 1        |
| File (a small generated image)                           | 1        |

Streets are called Musterstraße, addresses end in `example.com`. `GET /v1/me` returns `key.mode` as `test` and the ID of the test office.

## Create a test key [#create-a-test-key]

In [Settings, API keys](https://app.athaus.ai/einstellungen/api-keys) choose *Test* under **Key type**. Scopes and the restriction per resource work as for a live key, and so does the rule on who may create keys. The plan of the real office decides: Pro and Scale work, in Basic the API answers [`plan_required`](/en/api/errors#plan_required).

A test key works at `/v1` only, not at the MCP server and not in the app. It does not count against the connections of your plan, but an office has at most 10 valid test keys at a time: the eleventh is answered with [`test_key_limit_erreicht`](/en/api/fehlercodes#test_key_limit_erreicht) when you create it in the app. The test office is not visible in the app.

## Nothing leaves Athaus [#nothing-leaves-athaus]

In the test office no email, no SMS and no other message goes out. No portal receives anything, no connected CRM is written to, no listing becomes public. No AI model runs either.

A message you send to an inquiry then stands in the thread as sent, with a note that it was not delivered in test mode. The proposal ends as `executed`.

Webhooks keep going: the endpoints of a test key belong to the test office, receive its events and are signed the same way, so you can test your receiver. If an endpoint fails for good, it is disabled like any other (`disabledReason`, `disabledAt`); no email goes out for it.

## Tell events apart [#tell-events-apart]

Every [event](/en/api/v1/ereignisse) carries `livemode`: `true` for the real office, `false` for the test office. A proposal carries the same member.

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

## Decide proposals through the API [#decide-proposals-through-the-api]

In a real office a person says yes or no in the app, or a key with the scope `decide`. Nobody is in the test office, so there are two paths that a test key uses without that scope:

| Path                              | Effect                                                                    |
| --------------------------------- | ------------------------------------------------------------------------- |
| `POST /v1/proposals/{id}/approve` | Yes: the message stands in the thread as sent, the proposal is `executed` |
| `POST /v1/proposals/{id}/reject`  | No: nothing is sent, the proposal is `rejected`                           |

That lets you play through "`202` with a proposal, then yes" without the app ([What leaves the office](/en/api/v1/hinausgehen)). A live key needs the scope `decide` for them, otherwise `403` ([Deciding without a person](/en/api/v1/hinausgehen#decide)). Here too you only see the proposals of your own key.

## Reset [#reset]

`POST /v1/test/reset` restores the sample data. Everything else in the test office disappears, the old events too. The sample data itself reports no events: your receiver gets no flood of `created` events, only what you create or change afterwards. Webhook endpoints and keys stay, and the test office keeps its ID. The key needs write access to all resources. With a live key: `404`.

## Limits [#limits]

The same [limits](/en/api/v1/limits) as for live keys apply. The test office is also capped so it does not become storage: 200 listings, 1,000 contacts and 100 MB of files. Beyond that the API answers `403` with [`test_office_full`](/en/api/errors#test_office_full). Resetting makes room again.

## What can go wrong [#what-can-go-wrong]

| Status | Code                                                  | Cause                                         |
| ------ | ----------------------------------------------------- | --------------------------------------------- |
| `403`  | [`test_office_full`](/en/api/errors#test_office_full) | the test office reached its cap               |
| `409`  | [`test_office_busy`](/en/api/errors#test_office_busy) | the test office is being built or reset       |
| `403`  | [`plan_required`](/en/api/errors#plan_required)       | the plan of the real office has no API access |
| `404`  | [`not_found`](/en/api/errors#not_found)               | reset or decide with a live key               |
