Skip to content

Reference

Events stream

The server-sent events of a project: names, payloads, ordering, replay and when to reload.

Last updated:

The idea#

The editor and any client that wants to follow a project open one stream per project: GET /api/v1/projects/{id}/events, scope read. The stream is one way and text only. Commands do not travel on it; they are ordinary HTTP requests. MCP has no stream. The CLI command vukem-video events --project <id> prints it, one JSON object per line.

Connect#

PartMeaning
since (query)A revision. Same as Last-Event-ID, for clients that cannot set a header on the first request.
Last-Event-ID (header)Set by EventSource on every reconnect. When both are present the header wins.
Invalid valueA non-integer or negative value is E_VALIDATION (400) before the stream starts.
Response200, text/event-stream, no compression.

Authentication is checked before the response switches to a stream, so failures are normal JSON errors. EventSource does not retry any status other than 200; the client must. While the stream is open the server checks the credential again every 60 seconds and closes the stream when it is no longer valid.

Wire format#

Text
id: 42
event: batch.committed
data: {"project_id":"prj_7k2m9x4q1b","revision":42, ...}

data is one JSON object on one line. Only batch.committed has an id, and it is the revision. Timestamps are RFC 3339 UTC with milliseconds. A client ignores fields it does not know.

On connect the server sends retry: 1000 and an unnamed event with empty data, and repeats that empty event every 15 seconds as a heartbeat. Register listeners only for the five names below and treat 40 seconds without any event as a dead connection.

Events#

EventWhenMain fields
batch.committedAn edit, undo, redo, migration or import was committedrevision, base_revision, kind, actor, at, description, diff
project.updatedThe project was trashed or restoredstate (active or trashed), at
asset.updatedThe ingest state or progress of an asset changedasset_id, state, progress, error, updated_at
job.updatedA job changed state or progressjob_id, kind, state, progress, error, result, updated_at
resync.requiredThe server cannot bring this client up to date by replayrevision, reason

A diff too large for one event is replaced by diff_truncated: true and a changed list of at most 500 entries. A terminal job.updated carries result or error, so a client does not need to fetch the job.

Ordering and replay#

  • On one stream the batch.committed revisions are consecutive, each at most once. Across reconnects a client may see a revision it already has: ignore any revision less than or equal to the one you hold.
  • asset.updated and job.updated have no order guarantee and are not replayable. Keep the event with the newest updated_at for each asset or job. On connect the server sends the current state of what may have changed while you were away.
  • With a revision, the server replays what you missed from the log when the gap is at most 1,000 revisions.

resync.required has the reasons gap_too_large, before_floor (a migration or import lies in between) and client_ahead (the server has a different or restored database). It has no id. After it the server closes the stream: reload the project with GET /api/v1/projects/{id} and open a new stream with since set to the revision you loaded.

Common mistakes#

  • Reconnecting with a stale since after resync.required.
  • Expecting a response to an edit and its event to differ: both carry the same data for the same revision.

Next steps#