# Approve a proposal

Adresse: https://docs.athaus.ai/api/v1/referenz/approve-proposal

> Aufruf, Parameter, Antwort und Fehler von POST /v1/proposals/{id}/approve.

Typ: Referenz
Zuletzt aktualisiert: 2026-11-14

Says yes to a pending proposal: the message goes to the person who inquired, exactly as when a person clicks yes in the app, and the proposal ends as `approved` and then `executed`. Nobody reads the message first. Needs the key scope `decide` (and `approve`), which the office switches on when it creates the key; without it the answer is 403 `insufficient_permissions`. With a test key the scope is not needed: in the test office nobody else can say yes. Only a proposal of this API key can be decided, and only a reply or a follow-up to an inquiry: for any other kind, the publication of a listing included, which only a person says yes to in the app (the office's automation level decides whether it needs one), the answer is 403 `forbidden`. The decision runs the same code as the click in the app, with the same checks, the same 409 when the proposal was decided or has lapsed, and the same history, where it is recorded as made by this key, never by the person who created the key. Send an `Idempotency-Key` to retry safely. At most 30 decisions a minute per key. Needs write access to `inquiries`.

Braucht den Scope [`propose`](/api/v1/anmeldung#scopes).

## Aufruf [#aufruf]

```http
POST https://api.athaus.ai/v1/proposals/{id}/approve
```

### Parameter [#parameter]

**Pfad**

| Name | Typ             | Pflicht | Beschreibung          |
| ---- | --------------- | ------- | --------------------- |
| `id` | `string (uuid)` | ja      | UUID of the proposal. |

**Kopf**

| Name              | Typ      | Pflicht | Beschreibung                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Athaus-Version`  | `string` | nein    | Optional and carries nothing a client needs: the version is the path. Accepted when it says `v1` or `1`. Any other value is a 400 `api_version_unsupported`.                                                                                                                                                                                                                                                                         |
| `Idempotency-Key` | `string` | nein    | Makes a retry safe: the same key with the same body returns the first answer and writes nothing twice. A random value of at least 128 bits, for example a UUID, 1 to 255 characters. The key is kept for 24 hours and scoped to the API key and this operation. The same key with a different body is a 422; while the first request still runs it is a 409. Only successful answers are kept: after an error the key is free again. |

### Beispiel [#beispiel]

```bash
curl -X POST "https://api.athaus.ai/v1/proposals/0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17/approve" \
  -H "Authorization: Bearer ath_live_..." \
  -H "Idempotency-Key: $(uuidgen)"
```

## Antwort [#antwort]

Bei Erfolg kommt `200` mit `Proposal`.

### Proposal [#proposal]

| Feld               | Typ                          | Beschreibung                                                                                                                                                                                                                |
| ------------------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object`           | `string`                     | Immer `proposal`.                                                                                                                                                                                                           |
| `id`               | `string`                     | UUID of the proposal.                                                                                                                                                                                                       |
| `status`           | `string`                     | Eines von `pending`, `approved`, `executed`, `failed`, `rejected`, `expired`.                                                                                                                                               |
| `action`           | `string`                     | What the proposal does once it is approved. The list is open: new actions arrive, and a client treats an unknown one as a proposal it follows by status. Eines von `inquiry.reply`, `inquiry.follow_up`, `listing.publish`. |
| `target`           | `object`                     | What the action is about: an inquiry, or the listing (its `listingId`) to publish.                                                                                                                                          |
| `target.object`    | `string`                     | Eines von `inquiry`, `listing`.                                                                                                                                                                                             |
| `target.id`        | `string`                     |                                                                                                                                                                                                                             |
| `text`             | `string`                     | The message that goes to the person who inquired; for `listing.publish` a sentence naming the listing. Where a human changed a message before approving, the changed text.                                                  |
| `livemode`         | `boolean`                    | `false` for a proposal of the test office (test keys): approving it records the message as sent in the thread with a note that it was not delivered, and nothing leaves Athaus.                                             |
| `createdAt`        | `string (date-time)`         |                                                                                                                                                                                                                             |
| `decidedAt`        | `string (date-time) \| null` | When a human, an API key with the scope `decide` or the automation of the office said yes or no, or the proposal expired. Null while pending.                                                                               |
| `decidedBy`        | `object \| null`             | The API key that said yes or no. Null while pending and when a person or the office's automation decided.                                                                                                                   |
| `decidedBy.object` | `string`                     | Immer `api_key`.                                                                                                                                                                                                            |
| `decidedBy.id`     | `string`                     |                                                                                                                                                                                                                             |
| `decidedBy.name`   | `string \| null`             |                                                                                                                                                                                                                             |
| `executedAt`       | `string (date-time) \| null` | When the message was delivered, or the listing went online. Null until then.                                                                                                                                                |

### Köpfe der Antwort [#köpfe-der-antwort]

| Kopf                  | Beschreibung                                                                                                                                                                            |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Request-Id`          | Identifies this request. Quote it in a support request.                                                                                                                                 |
| `Athaus-Version`      | The API version of this response: v1.                                                                                                                                                   |
| `Athaus-Release`      | The release of v1 that answered, for example 1.0. A label for support and changelogs; no request can select it.                                                                         |
| `ETag`                | A strong entity tag of this state of the resource. Send it as `If-Match` to change or delete the resource only if it is unchanged, or as `If-None-Match` to read it only if it changed. |
| `RateLimit-Policy`    | The quota policy of the bucket that applies.                                                                                                                                            |
| `RateLimit`           | Remaining quota and seconds until the bucket is full again.                                                                                                                             |
| `Idempotent-Replayed` | `true` when this is the stored answer to an earlier request with the same Idempotency-Key.                                                                                              |

## Fehler [#fehler]

Jeder Fehler kommt als [Problem Details](/api/v1/fehler). Verzweige auf `code`, nicht auf `title` oder `detail`.

| Status | Codes                                                                                                            | Bedeutung                                                                                                   |
| ------ | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `400`  | [`invalid_id`](/api/errors#invalid_id), [`api_version_unsupported`](/api/errors#api_version_unsupported)         | Invalid request.                                                                                            |
| `401`  | [`unauthorized`](/api/errors#unauthorized)                                                                       | Missing or invalid API key.                                                                                 |
| `403`  | [`insufficient_permissions`](/api/errors#insufficient_permissions), [`plan_required`](/api/errors#plan_required) | The key lacks a right, or the plan does not include API access.                                             |
| `404`  | [`not_found`](/api/errors#not_found)                                                                             | Nothing under this ID.                                                                                      |
| `409`  | [`proposal_already_decided`](/api/errors#proposal_already_decided)                                               | The request conflicts with the state of the resource (for example a duplicate), or with an idempotency key. |
| `422`  |                                                                                                                  | The idempotency key was already used with a different request body.                                         |
| `429`  | [`rate_limited`](/api/errors#rate_limited)                                                                       | Rate limit exceeded.                                                                                        |
| `500`  | [`internal_error`](/api/errors#internal_error)                                                                   | Server error.                                                                                               |
