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.
bearerAuthAuthorizationBearer <token>Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).
copy?booleantrue 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.
falsetype?stringOnly 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?stringSet to none to leave out edge events. You receive an edge event only if you could read the edge with GET /edges/{id}.
"all""all""none"X-Marfa-Reach?stringOn 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.
^[0-9a-f]{64}$Last-Event-ID?stringThe 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.
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 asid:. stream_live: once the catch-up is over.stream_incomplete,catchup_too_old,cursor_aheadorreach_changed: last, before the stream closes.
text/event-stream- 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*stringThe frame's name, which is also its event:.
cursor*stringThe 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?stringOnly on a copy stream: the instance's ID, as GET / returns it.
reach?stringOnly 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,typehas more than 10 entries or is*, orLast-Event-IDisn't an event ID. A copy stream takes onlycopy=trueandedges=all, and both resume headers or neither; another stream takes noX-Marfa-Reach.unknown_type: atypeentry isn't registered.
application/json- 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- response
An error response.
error*What went wrong.
type_not_permitted: you can't read any type, or atypeentry names a type you can't read, with no subtype you can.
application/json- response
An error response.
error*What went wrong.
reach_changed: the reach in X-Marfa-Reach has changed. Rebuild the working copy.
application/json- 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- 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- 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- 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- 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- response
An error response.
error*What went wrong.
curl -X GET 'http://localhost:8600/events'"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"