# REST API: writing and idempotency

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

> Create, change and delete listings and contacts. Merge patch, Idempotency-Key for safe retries, ETag and If-Match against overwriting.

Type: Guide
Last updated: 2026-11-16

With `POST`, `PATCH`, `PUT` and `DELETE` your system writes `listings` and `contacts` in the office. The API key needs the scope `propose` and the level `write` on the resource ([Scopes and levels](/en/api/v1/anmeldung#scopes)). A key with only the scope `read` gets `403` and `insufficient_permissions`; nothing is written.

What you write is recorded in the office and in the history of the item under the name of the key. A change made through the API never flows back into a connected CRM.

## Create and change [#create-and-change]

* `POST` creates. A contact answers `201` with the object. A listing answers `202` with a receipt ([Listings](/en/api/v1/inserate#create-a-listing)). A POST never changes what exists: an email address, an address with its unit or a reference the office already has is `409`.
* `PATCH` changes as a merge patch (RFC 7396): a missing member stays, `null` clears it, a value replaces it, a list replaces the list. What cannot be cleared takes no `null`.
* `PUT /v1/listings/{externalListingId}` needs a complete body and then changes the listing like `PATCH`: what the body does not name stays, `null` clears it. An unknown id is `404`; with `createIfMissing=true` `PUT` creates it.
* A member the API does not know is `400`, and `errors[].name` names it. Nothing is silently dropped.
* The body is JSON (`Content-Type: application/json`, else `415`) and at most 512 KB (`413`). The one exception is `POST /v1/medias`: there the body is the file, at most 25 MB ([Photos and documents](/en/api/v1/inserate#media)).

## Delete [#delete]

A contact `DELETE` answers `200` with `{ "object": "contact", "id": "...", "deleted": true }`. A listing `DELETE` answers `202` with a receipt. A listing with upcoming viewings is `409` (`upcoming_viewings_exist`): deleting it would cancel the viewings, and that leaves the house. A published listing and a running brokerage agreement also stop the deletion (`listing_active`, `brokerage_agreement_active`).

## Retry without writing twice [#retry-without-writing-twice]

Send the header `Idempotency-Key` with a random value on every `POST` (for example a UUID, 1 to 255 characters). `PUT` and `DELETE` accept it too.

| Case                                              | Answer                                                             |
| ------------------------------------------------- | ------------------------------------------------------------------ |
| Same key, same body, the first request is done    | the same answer again, with the header `Idempotent-Replayed: true` |
| Same key, a different body                        | `422`, `idempotency_key_reused`                                    |
| The first request is still running                | `409`, `idempotency_key_in_use`, with `Retry-After`                |
| The first request ended in the middle of its work | `409`, `idempotency_outcome_unknown`                               |

Only successes are stored, for 24 hours, separated by API key and operation. After an error the key is free again. With `idempotency_outcome_unknown` nobody knows whether something was written: look at what is there, and retry with a new key.

The header is optional here. For operations that leave the office it is required ([What leaves the office](/en/api/v1/hinausgehen)).

## Do not overwrite: ETag and If-Match [#bedingt-schreiben]

A person can change something in the app while your system still works with the old state. With `If-Match` your system changes or deletes only if the state is still the one it read.

* Every single resource carries the header `ETag`: in `GET`, and in the answer to `POST`, `PATCH` and `PUT`. It changes with every change the API shows, including one a person made in the app. Lists have none. Treat the value as opaque and send it back unchanged, with its quotation marks.
* `PATCH`, `PUT` and `DELETE` accept `If-Match`. If the current `ETag` is in the list (several separated by commas), the change runs. Otherwise the API answers `412` with `precondition_failed`, and nothing is written. `If-Match: *` means: only if the object exists. A weak value (`W/"..."`) never matches.
* The check and the change are one step: two requests with the same `ETag` at the same time do not both change it, one gets `412`.
* The header is optional. Without it, the API writes without checking.
* On `PUT` of a listing, `If-Match` only changes. `If-None-Match: *` only creates (`412` if it exists already).
* On `GET`, `If-None-Match` with the current `ETag` answers `304` without a body. The request counts against the reading limit.

```bash
# 1. Read and keep the ETag
curl -si https://api.athaus.ai/v1/contacts/$ID -H "Authorization: Bearer $KEY" | grep -i '^etag'
# etag: "V1StGXR8_Z5jdHi6B-myTg"
```

```bash
# 2. Change only if nothing changed
curl -s -X PATCH https://api.athaus.ai/v1/contacts/$ID \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H 'If-Match: "V1StGXR8_Z5jdHi6B-myTg"' \
  -d '{"phone": null, "city": "Potsdam"}'
```

If the state has changed in the meantime, the API answers:

```json
{
  "type": "https://docs.athaus.ai/en/api/errors#precondition_failed",
  "title": "The condition of the request (If-Match or If-None-Match) does not hold for the current state of the resource, and nothing was written. Read the resource again, apply your change to the new state, and retry with the new ETag.",
  "status": 412,
  "detail": "The resource has changed since you read it.",
  "instance": "req_0f3a9c2b7d4e41a8b6c15e9d3a7f2b04",
  "errorSource": "headers",
  "code": "precondition_failed"
}
```

Read the object again, apply your change to the new state, and retry with the new `ETag`. An unreadable header is `400` with `errorSource` `headers`.

## Limits [#limits]

Writing has its own bucket: 2 requests per second, a burst of 60, separate from reading ([Limits](/en/api/v1/limits)).
