REST API: events
What happened in the office, available for 30 days. The same events that go to webhooks, filtered by type and time.
Last updated:
GET /v1/events returns what happened in the office: new inquiries and messages, booked, canceled and upcoming viewings, files that were read. These are the same events a webhook receives, with the same id. Use the list when you have no address, missed a webhook, or want to catch up after an outage.
curl "https://api.athaus.ai/v1/events?type=inquiry.received&limit=2" \
-H "Authorization: Bearer ath_live_..."{
"object": "list",
"data": [
{
"object": "event",
"id": "0190f3c1-22aa-7d10-9b3e-0f8e5c6a1d44",
"type": "inquiry.received",
"createdAt": "2026-11-12T08:14:03.512Z",
"apiVersion": "v1",
"livemode": true,
"data": {
"object": {
"object": "inquiry",
"id": "0190f3c1-2217-7a02-8c4b-5e1d7a9b3f10",
"listingId": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17",
"status": "new",
"source": "athaus",
"answered": false,
"replyable": true,
"name": "Mia K.",
"email": null,
"phone": null,
"contactId": null,
"contactConsent": "not_requested",
"seeker": null,
"createdAt": "2026-11-12T08:14:03Z",
"updatedAt": "2026-11-12T08:14:03Z"
}
}
}
],
"hasMore": true,
"nextCursor": "eyJzIjoiLWNyZWF0ZWRBdCIsLi4ufQ"
}What an event is
{ object: "event", id, type, createdAt, apiVersion, livemode, data: { object } }.
typeis one of the names in the webhook table. New types arrive without a new version: ignore what you do not know.data.objectis the resource the event is about, in the shape/v1reads it. It is in the state of now, not in the state of the event: if you need the state of back then, you have to keep it when it is delivered. If the resource no longer exists, you get{ "object": "viewing", "id": "...", "deleted": true }instead.- What a
GETdoes not return is not here either. Name, email and phone of a seeker appear only while they have released them to the office. apiVersionis the version thedatais shaped in.livemodeisfalsefor an event of the test office.
How long, and who sees what
An event is available for 30 days; after that GET /v1/events/{id} answers 404 and the list no longer shows it.
A key sees only the events of the resources it may read: without read on viewings it misses the three viewing types. It sees proposal.pending only for proposals it created itself. Asking for a type outside that is 403 (insufficient_permissions). A single event outside it is 404. The list needs the scope read, but no level on a resource of its own.
Filter and page
| Parameter | Effect |
|---|---|
type | only events of this type |
createdSince | only events from this instant on (ISO 8601, inclusive) |
createdBefore | only events before this instant |
limit, cursor | as everywhere, see Pagination |
The list is sorted by createdAt descending, newest first, and the order is fixed. There is no sort and no updatedSince: an event never changes.
Catch up after an outage
Keep the id of the newest event you processed and the time of its createdAt. Read with createdSince from that time, page to the end and skip what you already have. Events with the same time arrive exactly once, also across page boundaries.
curl "https://api.athaus.ai/v1/events/0190f3c1-22aa-7d10-9b3e-0f8e5c6a1d44" \
-H "Authorization: Bearer ath_live_..."Both operations are in the reference.
Keep reading
REST API: webhooks
Events to an address of your system: set one up, verify the signature, understand retries, rotate the secret.
REST API: pagination
Every list of /v1 returns one page and a way to the next. Listings use a page token, the other resources a cursor. No total count.
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.