Realtime protocol
rackend pushes record changes to clients over server-sent events (SSE) or a WebSocket. The SSE handshake is in the OpenAPI document; this page describes everything OpenAPI cannot: the event stream, the WebSocket messages, and the channel and collaboration protocols.
Topics and events
Section titled “Topics and events”A subscription names a topic and optional options:
| Topic | Receives |
|---|---|
records:{collection} |
Changes to any record of the collection |
records:{collection}/{record_id} |
Changes to one record |
| Option | Meaning |
|---|---|
filter |
Rule-language expression the record must match, e.g. room = 'lobby'. @collection is not available. |
expand |
Relations to include, as for GET .../records. |
fields |
Fields to send, as for GET .../records. |
An event:
{ "topic": "records:messages", "action": "create", "record": { "id": "…", "text": "hi" }, "ts": "2026-11-17T12:00:00.000Z" }actioniscreate,updateordelete.- You only receive a record you may view: the collection’s view rule is checked for every event and every subscriber, and so is your filter. Expanded relations follow the view rules of their collections.
- When an update makes a record leave what you may view (or stop matching your filter), you receive
deletewith"reason": "no_longer_visible". deleteevents carry the record as it was before it was deleted.- When your session is revoked, the connection closes within about 5 seconds.
Server-sent events
Section titled “Server-sent events”-
Open the stream:
GET /api/realtime. The first event isconnect:event: connectdata: {"client_id":"01a1…","resumed":false}A comment line is sent every 25 seconds to keep proxies from closing the connection.
-
Set the subscriptions with a normal API request, authenticated like any other (
Authorization: Bearer …or the session cookie). Tokens never go into the stream URL.Terminal window curl -X POST "$RACKEND_URL/api/realtime" \-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \-d '{"client_id":"01a1…","subscriptions":[{"topic":"records:messages","filter":"room = '\''lobby'\''"}]}'Each request replaces the whole subscription set. The first authenticated request binds the connection to that account; binding it to another account later fails with 403.
-
Events arrive with the topic as the event name and an id:
event: records:messagesid: 01a1….42data: {"topic":"records:messages","action":"create","record":{…},"ts":"…"}
Other events:
| Event | Data | Meaning |
|---|---|---|
connect |
{client_id, resumed} |
Stream opened (or resumed). |
resync |
{type: "resync", topic} |
Events of this topic may have been missed; reload what you show. |
close |
{type: "close", reason} |
The server ends the stream: session_revoked, slow_consumer or shutdown. |
Reconnecting. Browsers’ EventSource sends Last-Event-ID on reconnect. rackend keeps the last 256 events of each connection for 2 minutes; if everything since that id is still there, the stream resumes (resumed: true) and you keep your subscriptions. Otherwise you get a new client_id (subscribe again) or resync events for topics with gaps.
Limits. Too many connections from one IP answer 429. A client that cannot keep up is closed with slow_consumer.
WebSocket
Section titled “WebSocket”GET /api/ws upgrades to a WebSocket that carries JSON text messages. Browsers cannot set headers on WebSocket requests, so authenticate with an auth message (or the session cookie from an allowed origin). Connections without auth are anonymous and see what anonymous users may view.
The server’s first message:
{ "t": "connect", "client_id": "01a1…" }Client to server:
{ "t": "auth", "token": "rk_at_…" }{ "t": "sub", "id": 1, "topic": "records:messages", "filter": "room = 'lobby'", "expand": "author" }{ "t": "unsub", "id": 2, "topic": "records:messages" }{ "t": "ping" }idis yours; the reply to that message carries it.unsubremoves the subscription with thatid, or all subscriptions oftopic.authcan be sent again later, for example after refreshing the access token.
Server to client:
{ "t": "ack", "id": 1 }{ "t": "err", "id": 1, "code": "forbidden", "message": "…", "errors": { … } }{ "t": "record", "topic": "records:messages", "action": "create", "record": { … }, "ts": "…" }{ "t": "resync", "topic": "records:messages" }{ "t": "pong" }codeinerris a problem code from errors.md;errorsis present for validation problems.- The server pings every 25 seconds and closes the connection after 60 seconds without an answer.
- The server closes with code
4000and the reason as close reason:session_revoked,slow_consumer,shutdownortimeout.
Channels and presence
Section titled “Channels and presence”Channels carry ephemeral messages between the members of a named channel, such as room:42, with presence lists, on the same WebSocket. Superusers define channels in the admin UI (Channels) or with /api/channels:
| Field | Meaning |
|---|---|
pattern |
lobby (one channel) or room:* (one channel per key; room:42 has the key 42, at most 128 characters, available to rules as @channel.key). |
join_rule |
Who may join: null superusers only, "" anyone, or a rule with @request.auth.*, @channel.key and @collection.*. |
publish_rule |
Who may publish: null superusers only, "" every member, or a rule. |
presence |
Whether members see each other (default true). |
options |
max_members (1000), rate_per_s (20 messages per second per connection), max_payload (16384 bytes of data JSON), echo (false: senders do not receive their own messages). |


Example join rule: @collection.room_members.room = @channel.key && @collection.room_members.user = @request.auth.id.
Client to server:
{ "t": "join", "id": 3, "channel": "room:42", "meta": { "status": "typing" } }{ "t": "leave", "id": 4, "channel": "room:42" }{ "t": "pub", "id": 5, "channel": "room:42", "event": "cursor", "data": { "x": 10 } }{ "t": "meta", "id": 6, "channel": "room:42", "meta": { "status": "idle" } }Server to client:
{ "t": "msg", "channel": "room:42", "event": "cursor", "from": { "user_id": "…", "conn_id": "…" }, "data": { "x": 10 } }{ "t": "presence", "channel": "room:42", "kind": "sync", "members": [ { "user_id": "…", "conn_id": "…", "collection": "users", "meta": { … }, "joined_at": "…" } ] }{ "t": "presence", "channel": "room:42", "kind": "join", "members": [ … ], "replaced": "…" }{ "t": "presence", "channel": "room:42", "kind": "meta", "members": [ … ] }{ "t": "presence", "channel": "room:42", "kind": "leave", "members": [ … ], "reason": "forbidden" }join,leaveandmetareplyackorerr.pubreplies only when it has anid(errors are always sent). Failures use the problem codes:forbidden(rules),conflict(channel full),rate_limited,payload_too_large,bad_request(not joined),validation_failed(unknown channel, badmetaorevent).metais a JSON object of at most 1 KB;eventis 1 to 64 characters.- Messages are not stored. They reach the members joined at that moment, at most once.
- On
jointhe new member getssyncwith every member; the others getjoin. Joining again updatesmeta.conn_ididentifies a connection publicly (theclient_idstays secret). - A member whose connection drops stays listed for 3 seconds. When the same account joins again within that window, the others get one
joinwhosereplacednames the oldconn_id, and noleave, so online lists do not flicker. Otherwise everyone getsleave3 to 4 seconds after the drop. - Rules are checked on join and again every 30 seconds. A member who no longer passes the join rule is removed: everyone, including that member, gets
leavewithreason: "forbidden". Deleting a channel definition, or changing its pattern, removes its members the same way. user_idisnullfor anonymous members; superusers appear with the collection_superusers.
Collaborative editing
Section titled “Collaborative editing”A ydoc field holds a Yjs document. Clients edit it through a WebSocket that speaks the binary y-protocols sync and awareness protocol, so y-websocket (and editors built on it: Tiptap, BlockNote, CodeMirror and Monaco bindings) works unchanged:
GET /api/collab/{collection}/{record_id}/{field}y-websocket builds the URL from a server URL and a room name: use wss://your-host/api/collab/{collection}/{record_id} as the server URL and the field name as the room.
Authentication
Section titled “Authentication”- Cookie or
Authorizationheader on the upgrade, as for/api/ws(cookie sessions need an allowedOrigin). - Browsers cannot set headers on WebSockets, and tokens never go into URLs. Instead, fetch a ticket with the access token and pass it as the
ticketquery parameter. A ticket works once, for 30 seconds, for the document it was issued for; fetch a new one before every reconnect.
POST /api/collab/{collection}/{record_id}/{field}/ticket → { "ticket": "…", "expires_in": 30 }GET /api/collab/{collection}/{record_id}/{field}?ticket=…examples/collab-editor shows a Tiptap editor with ticket refresh on reconnect.
Access
Section titled “Access”- Connecting needs the view rule of the record (otherwise
404, before the upgrade). - Changes need the update rule. Without it the connection is read-only: the client receives the document and awareness, but its updates are dropped and answered with message type
100, a byte array holding{"code": "read_only", "message": "…"}. Withy-websocket, read it withprovider.messageHandlers[100] = (encoder, decoder) => …andlib0/decoding.readVarUint8Array(decoder). - Both rules are checked again every 30 seconds: losing view access closes the connection (code 4000,
forbidden), losing update access makes it read-only. - A document that would exceed the field’s
max_size(default 10 MB) rejects further updates with{"code": "too_large"}. - Turn off y-websocket’s BroadcastChannel (
disableBc: true): it syncs tabs of the same browser directly, past the server and its read-only check.
Persistence
Section titled “Persistence”- Updates are appended to the database every 250 ms and folded into the record’s column (compaction) after 500 updates, after 30 seconds without updates, when the document unloads (60 seconds after the last client left) and on shutdown. A crash loses at most the last 250 ms on the server; connected clients still hold those edits and send them again when they reconnect.
- While a document is edited, the record’s
updatedchanges at most every 30 seconds and record subscribers get anupdateevent. Theydocfield never appears in record JSON and cannot be used in rules or set through the records API. - Awareness (cursors, selections, names) is relayed in memory only.
- Deleting the record closes its documents (close reason
deleted) and removes their stored updates.
State over HTTP
Section titled “State over HTTP”GET /api/collab/{collection}/{record_id}/{field}/state → application/octet-stream (view rule)PUT /api/collab/{collection}/{record_id}/{field}/state ← application/octet-stream (update rule)Both use one Yjs update in the v1 encoding (Y.encodeStateAsUpdate(doc), Y.applyUpdate(doc, bytes)), for server-side rendering, exports and backups. PUT replaces the stored document and disconnects its editors (close reason replaced). Yjs merges rather than replaces, so clients must start from a new Y.Doc after a replace, or their old content comes back with their next sync.