REST-API: was das Büro verlässt
Anfragenden antworten und nachfassen. Wann eine Nachricht sofort hinausgeht, wann ein Vorschlag auf ein Ja wartet (202) und wie du das Ergebnis liest.
Zuletzt aktualisiert:
Manche Operationen erreichen eine Person außerhalb des Büros. Heute gibt es drei, zwei bei einer Anfrage und eine beim Inserat:
| Pfad | Was geschieht |
|---|---|
POST /v1/inquiries/{id}/messages | eine Antwort an die Person, die angefragt hat |
POST /v1/inquiries/{id}/followUps | ein Nachfassen; ohne text mit dem Standardtext von Athaus |
POST /v1/listings/{externalListingId}/publish | das Inserat geht online; Antwort 200 mit dem Inserat oder 202 mit einem Vorschlag (Inserate) |
Eine E-Mail lässt sich nicht zurückholen. Darum entscheidet dein Key allein nicht, ob sie hinausgeht.
Hinausgehen oder warten
Die Regel ist dieselbe wie beim MCP-Werkzeug draft_reply. Eine Nachricht geht nur dann sofort hinaus, wenn beides gilt:
- Der Key hat den Scope
approve. - Das Büro hat diese Art Nachricht in der App unter Automatik auf "Automatisch" gestellt.
| Key | Büro | Antwort |
|---|---|---|
approve | Automatisch | 201, die Nachricht ist eingereiht |
approve | Erst fragen | 202, ein Vorschlag wartet |
nur propose | beliebig | 202, ein Vorschlag wartet |
nur read | beliebig | 403, insufficient_permissions |
| beliebig | Aus | 409, automation_disabled |
Auch 201 heißt nicht "zugestellt". Die E-Mail steht in der Warteschlange; zugestellt ist sie, sobald der Vorschlag executed zeigt.
Der Key braucht außerdem die Stufe write auf inquiries.
Die Stufe lesen
GET /v1/automations nennt für jede Art von Aktion die Stufe des Büros: off, ask oder auto. GET /v1/automations/reply liefert die Stufe für Antworten, follow_up die für das Nachfassen. Lies sie vor dem Senden, wenn du wissen willst, ob eine Nachricht mit 201 oder 202 antwortet. Setzen kannst du eine Stufe über die API nicht: Das tut in der App, wer das Büro verwaltet. Ein Test-Key sieht die Stufen seines Testbüros. Der Key braucht die Stufe read auf inquiries.
Der Kopf Idempotency-Key ist Pflicht
Ohne ihn antwortet die API 400 mit idempotency_key_missing, und nichts läuft. Schicke je Nachricht eine neue UUID und nutze sie nur wieder, um genau diese Anfrage zu wiederholen.
Eine Wiederholung bekommt dieselbe Antwort mit Idempotent-Replayed: true, auch eine 202, mit demselben Vorschlag. Ein zweiter entsteht nie. Die gespeicherte Antwort zeigt den Stand des ersten Aufrufs: Den heutigen liest du unter GET /v1/proposals/{id}. Die übrigen Regeln stehen unter Schreiben.
Die 202 und der Vorschlag
curl -X POST https://api.athaus.ai/v1/inquiries/0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17/messages \
-H "Authorization: Bearer ath_live_..." \
-H "Idempotency-Key: 6f1d9a4e-2b0c-4d7e-8a35-91c7e2f0b8d3" \
-H "Content-Type: application/json" \
-d '{"text":"Guten Tag, die Wohnung ist noch verfügbar. Gern zeige ich sie Ihnen diese Woche."}'HTTP/1.1 202 Accepted
Location: /v1/proposals/0190f3b8-5a21-7c34-9e10-4d8a6b2c7f15{
"object": "proposal",
"id": "0190f3b8-5a21-7c34-9e10-4d8a6b2c7f15",
"status": "pending",
"action": "inquiry.reply",
"target": { "object": "inquiry", "id": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17" },
"text": "Guten Tag, die Wohnung ist noch verfügbar. Gern zeige ich sie Ihnen diese Woche.",
"livemode": true,
"createdAt": "2026-11-12T09:14:03Z",
"decidedAt": null,
"decidedBy": null,
"executedAt": null
}Es ist nichts hinausgegangen. Eine Person im Büro sieht den Vorschlag in der App und sagt Ja oder Nein. Über die API entscheidet nur ein Key mit dem Scope decide (Ohne Person entscheiden).
Bei publish ist action listing.publish und target das Inserat (listingId); executedAt ist gesetzt, sobald es online ist.
Die Liste der Werte von action ist offen: Es kommen neue dazu, ohne dass das ein Bruch ist. Behandle einen unbekannten Wert als Vorschlag, den du nur über status verfolgst.
Zustände
GET /v1/proposals/{id} liefert den Vorschlag, GET /v1/proposals die Liste (Cursor wie überall, Filter status, Sortierung createdAt). Ein Key sieht nur die Vorschläge, die er selbst angelegt hat. Der Vorschlag eines anderen ist 404.
status | Bedeutung |
|---|---|
pending | wartet auf ein Ja oder Nein |
approved | Ja gesagt, die E-Mail steht in der Warteschlange, noch nicht zugestellt |
executed | zugestellt (executedAt ist gesetzt) |
failed | Ja gesagt, aber die Zustellung gab nach allen Wiederholungen auf |
rejected | eine Person hat Nein gesagt |
expired | verfallen: ein neuerer Vorschlag derselben Art zur selben Anfrage hat ihn ersetzt, oder das Büro hat die Sache selbst erledigt |
Es gibt keine Frist. Ein Vorschlag wartet, bis jemand entscheidet oder er verfällt. Frag nicht jede Sekunde ab: Ein Aufruf alle paar Minuten reicht.
text ist die Nachricht, wie sie hinausgeht. Hat eine Person sie vor dem Ja geändert, steht dort der geänderte Text.
Was die API ablehnt
| Status | Code | Ursache |
|---|---|---|
400 | idempotency_key_missing | der Kopf fehlt |
400 | invalid_body | ein unbekanntes Feld, ein leerer Text, oder der Text behauptet etwas, das nicht am Inserat steht (errors[].name ist text) |
404 | not_found | keine solche Anfrage in diesem Büro |
409 | address_missing | die Person ist über Athaus nicht erreichbar: kein Konto und keine E-Mail-Adresse |
409 | automation_disabled | das Büro hat diese Art Nachricht ausgeschaltet; es wird nichts vorbereitet |
Der Text wird gegen die Fakten am Inserat geprüft, bevor etwas entsteht. Ein Key ist keine Quelle von Fakten: Was nicht am Inserat steht, schreibt die API nicht in eine E-Mail. Besichtigungen absagen oder verschieben und ein Inserat löschen, das Besichtigungen hat, gibt es bei /v1 noch nicht.
Ohne Person entscheiden
Standardmäßig sagt eine Person Ja. Das Büro kann einem Key das Recht geben, es selbst zu tun: den Scope decide. Dann gibt POST /v1/proposals/{id}/approve den Vorschlag frei und POST /v1/proposals/{id}/reject verwirft ihn, ohne dass jemand die Nachricht vorher liest.
Das Risiko trägt das Büro. Mails an Kunden und Anfragende gehen hinaus, ohne dass eine Person sie gesehen hat, und eine E-Mail lässt sich nicht zurückholen. Gib decide nur einem Key, dessen Texte du vertraust.
Wie es gilt:
decidesetztapproveund Schreibzugriff aufinquiriesvoraus. Ihn schaltet nur die Leitung des Büros beim Anlegen des Keys ein, in der App unter Einstellungen, API-Keys, mit einer Bestätigung. Kein bestehender Key hat ihn, auch keiner mitapprove.GET /v1/menennt ihn unterkey.scopes.- Ohne
decideantwortet der Aufruf mit403insufficient_permissions. - Ein Key entscheidet nur die Vorschläge, die er selbst angelegt hat, und nur Antworten und Nachfassen bei einer Anfrage. Alles andere ist
403forbiddenoder, bei fremden Vorschlägen,404. - Der Aufruf läuft durch denselben Code wie das Ja in der App: dieselben Prüfungen, dieselbe Frist, dieselbe Antwort
409proposal_already_decidedbei einem entschiedenen oder verfallenen Vorschlag, dieselben Folgen. Mit einemIdempotency-Keyist ein Wiederholen sicher; ohne ihn ist die zweite Entscheidung ein409. - Im Verlauf, am Vorschlag (
decidedBy) und, wo die Nachricht im Haus in den Faden geschrieben wird, in der Nachricht steht der Key mit Name und Id, nicht die Person, die ihn angelegt hat. Geht die Mail aus einem Postfach, steht der Key am Vorschlag und im Verlauf, und der Faden zeigt die Mail des Postfachs. - Höchstens 30 Entscheidungen je Minute und Key, mit einem Stoß von 10 (Grenzen). Die Grenzen dessen, was ein Ja auslöst, gelten weiter.
- Eine Anfrage von außerhalb ohne Faden in einem Postfach des Büros hat keinen Weg für die Mail:
409mailbox_not_connected, der Vorschlag bleibt offen. Ein Key hat kein eigenes Postfach, das als Ausweg dient. - Geht die Mail aus dem Postfach eines Mitglieds, weil dort der Faden der Anfrage liegt, geht sie von diesem Postfach ab, während am Vorschlag der Key steht.
Im Testmodus
Mit einem Test-Key geht nichts hinaus, auch nach einem Ja nicht. Du kannst den Vorschlag selbst entscheiden: POST /v1/proposals/{id}/approve oder /reject, ohne den Scope decide. Die Nachricht steht dann im Verlauf als gesendet, mit dem Vermerk, dass sie nicht zugestellt wurde (Testmodus).
Grenzen
Diese Operationen nutzen den Eimer fürs Schreiben (Grenzen). Eine gedrosselte Anfrage läuft nie.
Weiter lesen
REST-API: Schreiben und Idempotenz
Inserate und Kontakte anlegen, ändern und löschen. Merge Patch, Idempotency-Key für sichere Wiederholungen, ETag und If-Match gegen Überschreiben.
REST-API: Anmeldung mit einem API-Key
Jeder Aufruf von /v1 trägt einen API-Key als Bearer-Token. Wo du ihn bekommst, welche Scopes er trägt und was nicht geht.
REST-API: Fehler als Problem Details
Jeder Fehler von /v1 ist ein Problem nach RFC 9457 mit echtem HTTP-Status, einem Code zum Verzweigen und einer Request-Id für den Support.
REST-API: Limits und Drossel
Wie viele Aufrufe /v1 je Schlüssel und je Büro annimmt, welche Köpfe den Stand zeigen und was bei einem 429 zu tun ist.