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#
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"}| Field | What it holds |
|---|---|
seq | The position of the event in the project, growing by one or more each time |
id | The event id, the same as the id of the webhook payload |
type | The event type; the webhooks page lists all 20 |
branch, doc_id, doc_type | Where it happened, when it concerns a branch or a document |
actor, actor_name | Who did it, as <kind>:<id> (human, agent, token or system) and a display name |
data | Details that depend on the event |
created_at | ISO 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-IDheader, which browsers'EventSourcesends 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:
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
readscope. 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
429with coderate_limited. - On the Free plan, the stream answers
402with codefeature.
Recent events#
GET /p/<project>/v1/events lists recent events, newest first, on every plan. It needs the read scope.
curl "https://api.galerne.cloud/p/acme/v1/events?limit=50" -H "Authorization: Bearer gal_…"{ "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.