REST API: what leaves the office
Reply to and follow up with people who inquired. When a message goes out at once and when a proposal waits for a yes (202), and how to read the outcome.
Last updated:
Some operations reach a person outside the office. Today there are three, two on an inquiry and one on a listing:
| Path | What happens |
|---|---|
POST /v1/inquiries/{id}/messages | a reply to the person who inquired |
POST /v1/inquiries/{id}/followUps | a follow-up; without text, with the standard text from Athaus |
POST /v1/listings/{externalListingId}/publish | the listing goes online; the answer is 200 with the listing or 202 with a proposal (Listings) |
An email cannot be taken back. So your key alone does not decide whether it goes out.
Go out or wait
The rule is the same as for the MCP tool draft_reply. A message goes out right away only if both hold:
- The key has the scope
approve. - The office has set this kind of message to "Automatic" in the app under automation.
| Key | Office | Answer |
|---|---|---|
approve | Automatic | 201, the message is queued |
approve | Ask first | 202, a proposal waits |
only propose | any | 202, a proposal waits |
only read | any | 403, insufficient_permissions |
| any | Off | 409, automation_disabled |
Even 201 does not mean "delivered". The email sits in the queue; it is delivered once the proposal reads executed.
The key also needs the level write on inquiries.
Read the level
GET /v1/automations names the level of the office for every kind of action: off, ask or auto. GET /v1/automations/reply returns the level for replies, follow_up the one for follow-ups. Read it before sending if you want to know whether a message answers 201 or 202. You cannot set a level through the API: whoever manages the office does that in the app. A test key sees the levels of its test office. The key needs the level read on inquiries.
The Idempotency-Key header is required
Without it the API answers 400 with idempotency_key_missing, and nothing runs. Send a new UUID per message and reuse it only to retry exactly that request.
A retry gets the same answer with Idempotent-Replayed: true, a 202 included, with the same proposal. A second one is never created. The stored answer shows the state of the first call: read today's under GET /v1/proposals/{id}. The other rules are under Writing.
The 202 and the proposal
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":"Hello, the apartment is still available. I would be glad to show it to you this week."}'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": "Hello, the apartment is still available. I would be glad to show it to you this week.",
"livemode": true,
"createdAt": "2026-11-12T09:14:03Z",
"decidedAt": null,
"decidedBy": null,
"executedAt": null
}Nothing has gone out. A person in the office sees the proposal in the app and says yes or no. Through the API only a key with the scope decide decides (Deciding without a person).
For publish, action is listing.publish and target is the listing (listingId); executedAt is set once it is online.
The list of action values is open: new ones arrive, and that is no break. Treat an unknown value as a proposal that you follow by status only.
States
GET /v1/proposals/{id} returns the proposal, GET /v1/proposals the list (cursor as everywhere, filter status, sort createdAt). A key sees only the proposals it created itself. Someone else's proposal is 404.
status | Meaning |
|---|---|
pending | waits for a yes or no |
approved | yes was said, the email is in the queue, not yet delivered |
executed | delivered (executedAt is set) |
failed | yes was said, but delivery gave up after all retries |
rejected | a person said no |
expired | lapsed: a newer proposal of the same kind for the same inquiry replaced it, or the office handled the matter itself |
There is no deadline. A proposal waits until someone decides or it lapses. Do not poll every second: a call every few minutes is enough.
text is the message as it goes out. If a person changed it before saying yes, the changed text is there.
What the API rejects
| Status | Code | Cause |
|---|---|---|
400 | idempotency_key_missing | the header is missing |
400 | invalid_body | an unknown field, an empty text, or the text states something that is not on the listing (errors[].name is text) |
404 | not_found | no such inquiry in this office |
409 | address_missing | the person has no way to be reached through Athaus: no account and no email address |
409 | automation_disabled | the office has switched this kind of message off; nothing is prepared |
The text is checked against the facts on the listing before anything is created. A key is not a source of facts: what is not on the listing, the API does not put into an email. Declining, cancelling or moving viewings, and deleting a listing that has viewings, do not exist at /v1 yet.
Deciding without a person
By default a person says yes. The office can give a key the right to do it itself: the scope decide. Then POST /v1/proposals/{id}/approve approves the proposal and POST /v1/proposals/{id}/reject rejects it, with nobody reading the message first.
The risk is the office's. Mails to customers and inquirers go out without a person having seen them, and an email cannot be taken back. Give decide only to a key whose texts you trust.
How it works:
decideneedsapproveand write access toinquiries. Only the management of the office switches it on, when the key is created, in the app under Settings, API keys, with a confirmation. No existing key has it, not even one withapprove.GET /v1/melists it underkey.scopes.- Without
decidethe call answers403insufficient_permissions. - A key decides only the proposals it created itself, and only replies and follow-ups to an inquiry. Anything else is
403forbiddenor, for a foreign proposal,404. - The call runs the same code as the yes in the app: the same checks, the same expiry, the same
409proposal_already_decidedfor a decided or lapsed proposal, the same effects. With anIdempotency-Keya retry is safe; without one the second decision is a409. - The history, the proposal (
decidedBy) and, where the message is written into the thread in the house, the message name the key, with its name and id, not the person who created it. If the mail leaves from a mailbox, the key is on the proposal and in the history, and the thread shows the mailbox's mail. - At most 30 decisions a minute per key, with a burst of 10 (Limits). The limits of what a yes triggers stay in force.
- An inquiry from outside with no thread in a mailbox of the office has no way for the mail:
409mailbox_not_connected, and the proposal stays open. A key has no mailbox of its own to fall back on. - If the mail leaves from a member's mailbox because the thread of the inquiry lives there, it leaves from that mailbox while the proposal names the key.
In test mode
With a test key nothing goes out, not even after a yes. You can decide the proposal yourself: POST /v1/proposals/{id}/approve or /reject, without the scope decide. The message then stands in the thread as sent, with a note that it was not delivered (Test mode).
Limits
These operations use the bucket for writing (Limits). A throttled request never runs.
Keep reading
REST API: writing and idempotency
Create, change and delete listings and contacts. Merge patch, Idempotency-Key for safe retries, ETag and If-Match against overwriting.
REST API: authentication with an API key
Every call to /v1 carries an API key as a bearer token. Where to get one, which scopes it carries and what does not work.
REST API: errors as problem details
Every error from /v1 is an RFC 9457 problem with a real HTTP status, a code to branch on and a request id for support.
REST API: limits and throttling
How many calls /v1 accepts per key and per office, which headers show the state and what to do on a 429.