List proposals
Request, parameters, response and errors of GET /v1/proposals.
Last updated:
Returns the proposals this API key created, newest first by default. A proposal appears when an operation that reaches people outside the office, for example POST /inquiries/{id}/messages, is not allowed to go out right away; the answer to that call is 202 with a link to it. Filter by status to find what still waits (pending). Proposals of other keys, of people and of the automation of the office are not listed. A proposal has no time of change, so updatedSince is rejected as an unknown parameter. Needs read access to inquiries.
Requires the scope read.
Request
GET https://api.athaus.ai/v1/proposalsParameters
Query
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | no | Page size, 1 to 100. More than 100 is rejected, never capped. Default 50. |
cursor | string | no | Opaque value from nextCursor of the previous page. |
sort | string | no | Field to order by. Newest first by default. One of createdAt, -createdAt. Default -createdAt. |
status | string | no | Only proposals in this status. One of pending, approved, executed, failed, rejected, expired. |
Header
| Name | Type | Required | Description |
|---|---|---|---|
Athaus-Version | string | no | 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. |
Example
curl "https://api.athaus.ai/v1/proposals?limit=10" \
-H "Authorization: Bearer ath_live_..."Response
On success the status is 200 with ProposalList.
ProposalList
| Field | Type | Description |
|---|---|---|
object | string | Always list. |
data | Proposal[] | |
hasMore | boolean | True if another page follows. |
nextCursor | string | null | Pass as cursor to get the next page. Null on the last page. |
Proposal
| Field | Type | Description |
|---|---|---|
object | string | Always proposal. |
id | string | UUID of the proposal. |
status | string | One of 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. One of 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 | One of 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 | Always 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. |
Response headers
| Header | Description |
|---|---|
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. |
RateLimit-Policy | The quota policy of the bucket that applies. |
RateLimit | Remaining quota and seconds until the bucket is full again. |
Errors
Every error arrives as problem details. Branch on code, not on title or detail.
| Status | Codes | Meaning |
|---|---|---|
400 | invalid_query, api_version_unsupported | Invalid request. |
401 | unauthorized | Missing or invalid API key. |
403 | insufficient_permissions, plan_required | The key lacks a right, or the plan does not include API access. |
404 | not_found | Nothing under this ID. |
429 | rate_limited | Rate limit exceeded. |
500 | internal_error | Server error. |
Keep reading
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.