docs menu

Event stream

Every change in a project is recorded as an event: the same events webhooks send. Webhooks push them to a public URL. The event stream lets a program that runs all the time, such as an agent that waits for new uploads or a search indexer, read them live over one HTTP connection, with no public URL of its own.

The stream is part of Pro and up. The list of recent events works on every plan.

Open the stream#

bash
curl -N "https://api.galerne.cloud/p/acme/v1/events/stream?types=doc.published,media.*" \
  -H "Authorization: Bearer gal_…"

The answer is a Server-Sent Events stream. Each message carries the event type as event, the event sequence number as id, and the event as JSON in data:

event: doc.published
id: 4182
data: {"seq":4182,"id":"evt_8KfQ2x…","type":"doc.published","branch":"main","doc_id":"harbours","doc_type":"post","actor":"human:acc_…","actor_name":"Marie","data":{},"created_at":"2026-10-16T09:22:41.000Z"}
FieldWhat it holds
seqThe position of the event in the project, growing by one or more each time
idThe event id, the same as the id of the webhook payload
typeThe event type; the webhooks page lists all 20
branch, doc_id, doc_typeWhere it happened, when it concerns a branch or a document
actor, actor_nameWho did it, as <kind>:<id> (human, agent, token or system) and a display name
dataDetails that depend on the event
created_atISO 8601 time

When nothing happens for 25 seconds, the server sends an event: ping with empty data, so proxies keep the connection open.

Filter#

types takes a comma-separated list of event types. A type ending in .* matches every event that starts with the prefix: review.* matches review.requested, review.approved and review.changes_requested. Without types, the stream sends everything.

Resume#

Without a position, the stream starts with the events that happen after you connect. To pick up where you stopped, send the last id you received:

  • in the Last-Event-ID header, which browsers' EventSource sends on its own when it reconnects;
  • or as ?since=<seq>.

The stream then replays every event after that one, in order, and continues live. Events are kept 90 days.

In a browser or in Node.js#

EventSource cannot send an Authorization header, so read the stream with fetch on a server or in a worker:

ts
const response = await fetch('https://api.galerne.cloud/p/acme/v1/events/stream?types=media.uploaded', {
  headers: { Authorization: `Bearer ${process.env.GALERNE_TOKEN}` },
})
const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader()
let buffer = ''
while (true) {
  const { value, done } = await reader.read()
  if (done) break
  buffer += value
  const messages = buffer.split('\n\n')
  buffer = messages.pop() ?? ''
  for (const message of messages) {
    const data = message.split('\n').find((line) => line.startsWith('data: '))?.slice(6)
    if (!data) continue
    const event = JSON.parse(data)
    console.log(event.type, event.doc_id)
  }
}

Access and limits#

  • The token needs the read scope. The stream sends every event of the project, whatever the token's type or branch rules.
  • A token may hold 5 open streams at once, and a project 50. Over that, the API answers 429 with code rate_limited.
  • On the Free plan, the stream answers 402 with code feature.

Recent events#

GET /p/<project>/v1/events lists recent events, newest first, on every plan. It needs the read scope.

bash
curl "https://api.galerne.cloud/p/acme/v1/events?limit=50" -H "Authorization: Bearer gal_…"
json
{ "events": [{ "seq": 4182, "id": "evt_8KfQ2x…", "type": "doc.published", "branch": "main", "doc_id": "harbours", "doc_type": "post", "actor": "human:acc_…", "actor_name": "Marie", "data": {}, "created_at": "2026-10-16T09:22:41.000Z" }] }

limit goes up to 500, 50 by default. To page back, pass the smallest seq you got as before.