buckets

Follow changes

Server-sent events (Accept: text/event-stream) of the bucket's file changes, so clients can stop polling /tree.

Events:

  • ready: {"cursor"} — replay (if any) is done, live changes follow. cursor may be absent if the feed has seen no change yet.
  • changes: {"cursor", "changes": [{"path", "op": "add" | "update" | "delete", "size"?, "xetHash"?, "uploadedAt"?, "mtime"?, "mtimeNanos"?}]} — a batch of changes coalesced over ~200ms. An update only carries the fields that changed (an identical re-upload has just uploadedAt); mtime/mtimeNanos are null when a re-upload cleared them. xetHash is omitted without content read access.
  • reset: {"reason": "cursor_too_old"} — the requested cursor/since is older than what the server buffers (about 15 minutes); the stream ends and the client must re-list. A since at or after the bucket's updatedAt never resets, however old.
  • reconnect: {"cursor"} — sent after 20 minutes or when the server shuts down (deploys), then the stream ends; reconnect with that cursor. Treat any other end of the stream the same way: reconnect with the last cursor you received.

A : ping comment is sent every 30s. Resume with ?cursor= (exclusive) or ?since= (inclusive); without either, only live changes are sent.

get/api/buckets/{namespace}/{repo}/events

Path parameters

namespacestring required
repostring required

Query parameters

cursorstring

Opaque cursor from a previous ready/changes event; resume after it

sincestring date-time

Resume from this instant instead of a cursor (e.g. the bucket's updatedAt you last saw)

Changes