Stream events (Server-Sent Events)

GET

/v1/events/stream

const url = 'https://api.aerandil.com/v1/events/stream';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

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

Server-Sent Events tail of the event log. The polling endpoint at GET /v1/events is the right contract for batched durable consumers (replayable, indifferent to downtime); the streaming surface exists for live agents that can’t afford the poll-sleep-poll latency.

Both surfaces emit the same EventRow shape — a client can swap between polling and streaming without re-tooling filters.

Resume. The Last-Event-ID request header (auto-set by browser EventSource on reconnect) carries the last observed seq and wins over the since query parameter.

Frames. The default frame has id: <seq> and data: <EventRow JSON>. An error frame (event: error) is emitted when an event row fails to serialise — the consumer reconnects with the last known id. Comment-only heartbeat frames (: keepalive\n\n) keep idle connections open across NAT/LB cull windows and are not modeled here (per the OAI registry, SSE comments are out of scope).

Authorizations

aerandil_oauth
events:read objects:read

Parameters

Header Parameters

Last-Event-ID

string

/^\d+$/

Resume cursor (last observed seq). Set automatically by browser EventSource on reconnect; wins over the since query parameter when both are present.

Query Parameters

since

integer

Numeric seq resume cursor for SDKs that don’t speak the standard Last-Event-ID reconnect header. Strict greater-than (seq > since). Loses to Last-Event-ID when both are set.

correlation_id

string format: uuid

Same shape as /v1/events?correlation_id=….

object_type

string

Same shape as /v1/events?object_type=….

property_id

string format: uuid

Same shape as /v1/events?property_id=… — the house a handset or desk is standing in.

Responses

200

Open Server-Sent Events stream. Runs until the client disconnects; idle connections are kept alive by : keepalive comment frames every ~15 seconds.

text/event-stream

One of: discriminator: event

object
object

object

data

required

One of: discriminator: kind

object

correlation_id

string format: uuid

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

object

kind

required

string

Allowed value: service

Allowed values: service

name

required

Service api_name (e.g. connector.opera_pms).

string

object

delegated_by

One of: discriminator: kind

object

kind

required

string

Allowed value: system

Allowed values: system

object

kind

required

string

Allowed value: service

Allowed values: service

name

required

Service api_name (e.g. connector.opera_pms).

string

kind

required

string

Allowed value: agent

Allowed values: agent

model

required

Model the agent ran with (e.g. claude-opus-4-7).

string

vendor

required

Issuer of the agent (e.g. anthropic, openai).

string

version

required

Version string under the vendor’s namespace.

string

seq

required

integer

required

string format: date-time

object

correlation_id

string format: uuid

required

string format: uuid

kind

required

string

Allowed value: object_updated

Allowed values: object_updated

object_type

required

string

principal

required

One of: discriminator: kind

object

kind

required

string

Allowed value: system

Allowed values: system

object

kind

required

string

Allowed value: service

Allowed values: service

name

required

Service api_name (e.g. connector.opera_pms).

string

object

delegated_by

One of: discriminator: kind

object

kind

required

string

Allowed value: system

Allowed values: system

object

kind

required

string

Allowed value: service

Allowed values: service

name

required

Service api_name (e.g. connector.opera_pms).

string

kind

required

string

Allowed value: agent

Allowed values: agent

model

required

Model the agent ran with (e.g. claude-opus-4-7).

string

vendor

required

Issuer of the agent (e.g. anthropic, openai).

string

version

required

Version string under the vendor’s namespace.

string

seq

required

integer

required

string format: date-time

object

correlation_id

string format: uuid

required

string format: uuid

kind

required

string

Allowed value: object_deleted

Allowed values: object_deleted

object_type

required

string

principal

required

One of: discriminator: kind

object

kind

required

string

Allowed value: system

Allowed values: system

object

kind

required

string

Allowed value: service

Allowed values: service

name

required

Service api_name (e.g. connector.opera_pms).

string

object

delegated_by

One of: discriminator: kind

object

kind

required

string

Allowed value: system

Allowed values: system

object

kind

required

string

Allowed value: service

Allowed values: service

name

required

Service api_name (e.g. connector.opera_pms).

string

kind

required

string

Allowed value: agent

Allowed values: agent

model

required

Model the agent ran with (e.g. claude-opus-4-7).

string

vendor

required

Issuer of the agent (e.g. anthropic, openai).

string

version

required

Version string under the vendor’s namespace.

string

seq

required

integer

required

string format: date-time

object

correlation_id

string format: uuid

from_id

required

string format: uuid

from_type

required

string

kind

required

string

Allowed value: object_linked

Allowed values: object_linked

link_type

required

string

principal

required

One of: discriminator: kind

object

kind

required

string

Allowed value: system

Allowed values: system

object

kind

required

string

Allowed value: service

Allowed values: service

name

required

Service api_name (e.g. connector.opera_pms).

string

object

delegated_by

One of: discriminator: kind

object

kind

required

string

Allowed value: system

Allowed values: system

object

kind

required

string

Allowed value: service

Allowed values: service

name

required

Service api_name (e.g. connector.opera_pms).

string

kind

required

string

Allowed value: agent

Allowed values: agent

model

required

Model the agent ran with (e.g. claude-opus-4-7).

string

vendor

required

Issuer of the agent (e.g. anthropic, openai).

string

version

required

Version string under the vendor’s namespace.

string

seq

required

integer

to_id

required

string format: uuid

to_type

required

string

required

string format: date-time

object

correlation_id

string format: uuid

from_id

required

string format: uuid

from_type

required

string

kind

required

string

Allowed value: object_unlinked

Allowed values: object_unlinked

link_type

required

string

principal

required

One of: discriminator: kind

object

kind

required

string

Allowed value: system

Allowed values: system

object

kind

required

string

Allowed value: service

Allowed values: service

name

required

Service api_name (e.g. connector.opera_pms).

string

object

delegated_by

One of: discriminator: kind

object

kind

required

string

Allowed value: system

Allowed values: system

object

kind

required

string

Allowed value: service

Allowed values: service

name

required

Service api_name (e.g. connector.opera_pms).

string

kind

required

string

Allowed value: agent

Allowed values: agent

model

required

Model the agent ran with (e.g. claude-opus-4-7).

string

vendor

required

Issuer of the agent (e.g. anthropic, openai).

string

version

required

Version string under the vendor’s namespace.

string

seq

required

integer

to_id

required

string format: uuid

to_type

required

string

required

string format: date-time

event

required

SSE default event name. On the wire the server omits the event: line for these frames; the OAI registry models the default name explicitly so generated SDKs can dispatch.

string

Allowed value: message

Allowed values: message

required

Stringified seq of the carried event row.

string

/^\d+$/

Headers

Cache-Control

string

Allowed value: no-store

Always no-store — forever-streaming body.