AthausDocs

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:

PathWhat happens
POST /v1/inquiries/{id}/messagesa reply to the person who inquired
POST /v1/inquiries/{id}/followUpsa follow-up; without text, with the standard text from Athaus
POST /v1/listings/{externalListingId}/publishthe 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:

  1. The key has the scope approve.
  2. The office has set this kind of message to "Automatic" in the app under automation.
KeyOfficeAnswer
approveAutomatic201, the message is queued
approveAsk first202, a proposal waits
only proposeany202, a proposal waits
only readany403, insufficient_permissions
anyOff409, 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.

statusMeaning
pendingwaits for a yes or no
approvedyes was said, the email is in the queue, not yet delivered
executeddelivered (executedAt is set)
failedyes was said, but delivery gave up after all retries
rejecteda person said no
expiredlapsed: 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

StatusCodeCause
400idempotency_key_missingthe header is missing
400invalid_bodyan unknown field, an empty text, or the text states something that is not on the listing (errors[].name is text)
404not_foundno such inquiry in this office
409address_missingthe person has no way to be reached through Athaus: no account and no email address
409automation_disabledthe 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:

  • decide needs approve and write access to inquiries. 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 with approve. GET /v1/me lists it under key.scopes.
  • Without decide the call answers 403 insufficient_permissions.
  • A key decides only the proposals it created itself, and only replies and follow-ups to an inquiry. Anything else is 403 forbidden or, 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 409 proposal_already_decided for a decided or lapsed proposal, the same effects. With an Idempotency-Key a retry is safe; without one the second decision is a 409.
  • 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: 409 mailbox_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

On this page