Skip to content
aerandil.com
GitHub

List events

GET
/v1/events
curl --request GET \
  --url 'https://api.aerandil.com/v1/events?order=asc' \
  --header 'Authorization: Bearer <token>'

Tail of the event log, oldest first. The events table is the architectural outbox — every accepted mutation appends one row in the same transaction as the projection update, so this endpoint is the CDC surface (webhooks sit on top of it). Keyset pagination on the BIGSERIAL seq; cursor is opaque base64url and wins over the numeric since alternative when both are present. correlation_id narrows to one action invocation’s events; object_type matches both object events (subject type) and link events (either endpoint type); property_id narrows to one house plus the property-less events. The server-clamped limit defaults to 100 and caps at 1000. order=desc flips to newest-first for audit browsing: the cursor then pages strictly backwards through history and since is rejected.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
cursor
string

Opaque base64url cursor from a prior response’s next_cursor. Wins over since when both are set.

since
integer

Numeric seq alternative to cursor for clients that track seq themselves. Strict greater-than filter (WHERE seq > since). Must be non-negative.

correlation_id
string format: uuid

Narrow to events emitted under a specific correlation id (typically one action invocation).

object_type
string

Narrow to events involving any of the given object types — one API name, or several comma-separated (object_type=hospitality.room,hospitality.housekeeping_task). Matches the subject type on object events and either endpoint type on link events.

property_id
string format: uuid

Narrow to one property’s events plus the property-less ones (tenant-level subjects such as a person, named events). An event’s property is derived when it is appended, from its subject’s tenancy scope — a link event takes its from endpoint’s, else its to endpoint’s — so a sibling property’s events are what this excludes.

limit
integer
>= 1 <= 1000

Page size. Default 100, server-clamps to 1000.

order
string
default: asc
Allowed values: asc desc

Sort order over seq. asc (default) is the CDC tail; desc is newest-first audit browsing, where cursor means strictly-less-than and since is rejected.

branch
string format: uuid

Read a branch’s own event stream instead of the main log (branch-and-time-travel §Branching). The seq/cursor namespace is the branch stream’s own, distinct from the main log’s; only the ascending tail is supported and the correlation_id / object_type / property_id / order=desc filters do not compose with it (422).

Responses

Section titled “Responses”

200

Section titled “200”

Page of events. next_cursor is omitted once the consumer catches up to the head of the log.

Media typeapplication/json
object
data
required
Array
One of: discriminator: kind
object
correlation_id
string format: uuid
id
required
string format: uuid
kind
required
string
Allowed value: object_created
Allowed values: object_created
object_type
required
string
principal
required
One of: discriminator: kind
object
kind
required
string
Allowed value: system
Allowed values: system
seq
required
integer
ts
required
string format: date-time
has_more
required
boolean
next_cursor

Opaque cursor for the next page; omitted when the consumer has caught up to the head of the log.

string
Example
{
  "data": [
    {
      "kind": "object_created",
      "principal": {
        "kind": "system"
      }
    }
  ]
}

Headers

Section titled “Headers”
Cache-Control
string
Allowed value: no-store

Always no-store — live data.

422

Section titled “422”

Validation error — invalid cursor / since / object_type / property_id / limit.