Event stream

Stream change events

Opens a Server-Sent Events stream of the changes to items and edges that you can read. Send Last-Event-ID to resume after a disconnect, or copy=true to follow a working copy.

GET
/events

Authorization

bearerAuth
headerAuthorizationBearer <token>

Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).

Query parameters

copy?boolean

true for a copy stream, which a working copy follows. It takes edges=all and no other parameter. Its stream_cursor and stream_live carry instance_id and reach, and its item frames carry listed.

Defaultfalse
type?string

Only send item events for these types and their subtypes: a comma-separated list of up to 10, such as core.note,app.*. A pattern matches the types you can read. Edge events aren't filtered. Leave it out for every type.

edges?string

Set to none to leave out edge events. You receive an edge event only if you could read the edge with GET /edges/{id}.

Default"all"
Value in"all""none"

Header parameters

X-Marfa-Reach?string

On a copy stream, the reach from the last stream_cursor or stream_live you received. Send it with Last-Event-ID to resume, and leave both out to start a new copy.

Match^[0-9a-f]{64}$
Last-Event-ID?string

The ID of the last event you received. Marfa replays every event after it that the log still holds, then goes live. Send it as the stream wrote it. Empty means none, except on a copy stream.

Response body

About errors

Returns the stream. Each frame's event: names it:

  • stream_cursor: first, where the log stands.
  • An event, such as item.created, with its event ID as id:.
  • stream_live: once the catch-up is over.
  • stream_incomplete, catchup_too_old, cursor_ahead or reach_changed: last, before the stream closes.
text/event-stream
  1. response

The stream's first frame, with no id:: where the log stood when the stream opened. If Marfa can't read the log within 5 seconds, an ordinary stream leaves it out, so don't wait for it, and a copy stream ends with stream_incomplete.

event_type*string

The frame's name, which is also its event:.

cursor*string

The ID of the latest event in the log, or 0 if it's empty. Read state after this frame, and you can resume from this ID without missing a change.

instance_id?string

Only on a copy stream: the instance's ID, as GET / returns it.

reach?string

Only on a copy stream: the reach to send as X-Marfa-Reach, to resume or to read the working copy's data.

  • validation_error: a parameter or header is invalid, or not one this endpoint takes. For example, type has more than 10 entries or is *, or Last-Event-ID isn't an event ID. A copy stream takes only copy=true and edges=all, and both resume headers or neither; another stream takes no X-Marfa-Reach.
  • unknown_type: a type entry isn't registered.
application/json
  1. response

An error response.

error*

What went wrong.

unauthorized: the request has no credential, or its credential is not valid. For a key that has expired, details.expired_at says when it expired.

application/json
  1. response

An error response.

error*

What went wrong.

  • type_not_permitted: you can't read any type, or a type entry names a type you can't read, with no subtype you can.
application/json
  1. response

An error response.

error*

What went wrong.

reach_changed: the reach in X-Marfa-Reach has changed. Rebuild the working copy.

application/json
  1. response

An error response.

error*

What went wrong.

contract_mismatch: X-Marfa-Contract names another contract version than this instance speaks, or is not a whole number. Nothing was done.

application/json
  1. response

An error response.

error*

What went wrong.

rate_limited: you sent too many requests. Wait for the number of seconds in Retry-After, then try again.

application/json
  1. response

An error response.

error*

What went wrong.

internal_error: Marfa failed in a way it didn't expect, and the request may not have completed. Read what you changed before you repeat a write.

application/json
  1. response

An error response.

error*

What went wrong.

  • stream_capacity_exhausted: the instance is serving as many streams as its operator allows. Try again later.
  • write_contention: the database was busy, and Marfa couldn't complete the request in time. Nothing changed. Try the request again.
application/json
  1. response

An error response.

error*

What went wrong.

insufficient_storage: the disk that holds the instance's data has no room for the request, or the request would leave less free than the instance keeps in reserve. Nothing changed, unless details.write_outcome is unknown, which means the write may have landed: read what you changed before you repeat it. Free space on the disk, then try the request again.

application/json
  1. response

An error response.

error*

What went wrong.

curl -X GET 'http://localhost:8600/events'
About errors
"event: stream_cursor\ndata: {\"event_type\":\"stream_cursor\",\"cursor\":\"1041\"}\n\nevent: stream_live\ndata: {\"event_type\":\"stream_live\",\"cursor\":\"1041\"}\n\nid: 1042\nevent: item.created\ndata: {\"event_type\":\"item.created\",\"item\":{\"id\":\"0199a9c4-7c1e-7d3a-9f2b-3c4d5e6f7a8b\",\"type\":\"core.note\",\"properties\":{\"title\":\"Reading list\",\"body\":\"Finish the chapter on tides.\"},\"state\":\"active\",\"tier\":\"library\",\"version\":1,\"schema_version\":0,\"source\":\"notes-app\",\"occurred_at\":\"2026-10-03T09:30:00.000Z\",\"created_at\":\"2026-10-03T09:30:00.000Z\",\"updated_at\":\"2026-10-03T09:30:00.000Z\"},\"metadata\":{\"item_id\":\"0199a9c4-7c1e-7d3a-9f2b-3c4d5e6f7a8b\",\"tags\":[],\"extensions\":{}}}\n\n"