openintentsdocs
Browse docs
previewThese docs describe OpenIntents as it is being built. Endpoints and payloads may change before launch.
View as Markdown

Events and live streams

Every intent and session keeps a timeline: its status changes and its steps, oldest first. Read it as a page, or follow it live as Server-Sent Events.

The event object

json
{
  "id": "evt_3b9f1a",
  "object": "event",
  "type": "status",
  "created_at": "2026-10-13T08:30:04Z",
  "data": { "status": "running" }
}

type says what data holds. New types may appear: skip the ones you don't know.

typeOfdata
statusintents, sessions{ status, reason? }: the new status, and why when there is a why (a failed intent's error code, say).
stepintents{ action }: what the agent did: open, look, click, type, read. Never what it typed.
checkoutintents{ merchant, total, currency }: the payment step was reached.
pagesessions{ url, title }: the session's page changed.
commandsessions{ id, type, status, typed_chars? }: a command ran.

An intent that moves to a fresh browser shows { "status": "queued", "reason": "browser_lost" }, and one tried again to get past a shop's check, { "status": "queued", "reason": "retrying" }. One that waits for its customer to sign in shows { "status": "requires_login", "reason": "login_required" }, then { "status": "queued", "reason": "signed_in" }. One whose agent asks your customer something to sign them in shows { "status": "requires_input", "reason": "code" } (or phone, email, approval), then { "status": "running", "reason": "answered" } (or declined, approved, expired). Never the answer itself.

A page of events

GET/v1/intents/{id}/events?limit=50
GET/v1/sessions/{id}/events?limit=50
json
{
  "object": "list",
  "data": [{ "id": "evt_3b9f1a", "object": "event", "type": "status", "data": { "status": "queued" } }],
  "next_cursor": "evt_3b9f1a"
}

Pass the next_cursor back as cursor for the next page.

Live streams

Ask the same endpoint for text/event-stream:

bash
curl -N https://api.openintents.io/v1/intents/int_7f3a2c/events \
  -H "Authorization: Bearer $OPENINTENTS_API_KEY" \
  -H "Accept: text/event-stream"
text
id: evt_3b9f1a
data: {"id":"evt_3b9f1a","object":"event","type":"status","created_at":"2026-10-13T08:30:00Z","data":{"status":"queued"}}

id: evt_3b9f2c
data: {"id":"evt_3b9f2c","object":"event","type":"status","created_at":"2026-10-13T08:30:01Z","data":{"status":"running"}}

: keep-alive
  • Past events come first, then new ones as they happen. Lines starting with : only keep the connection open.
  • Once the intent or session is over and its last event is sent, the stream closes.
  • To resume, reconnect with the last event's id in Last-Event-ID: you get what came after it, without repeats. A stream may also close on its own after a while; resuming picks it up.
  • Asking for the stream of something over, with nothing left to send, answers 204 No Content: stop there.
  • Too many open streams answer 429 with code: too_many_streams; try again shortly.

A browser's EventSource can't send an Authorization header, so follow streams from your server, or read the response body as a stream with fetch.

Events or webhooks

Webhooks tell your server about the changes that matter (completed, failed, payment required), whether or not anyone is watching. Event streams show everything as it happens, to whoever follows: a progress view for your users, say.