The native client protocol
The first-party clients use a WebSocket at /ws and the REST routes under
/api/. They are not a stable public API — they change with the clients, and
are versioned by PROTOCOL_VERSION in packages/protocol.
Every REST route, with the body or query it takes and who may call it, is
described in packages/server/openapi.json:
OpenAPI 3.0, generated from the schemas the server validates requests with, and
checked in CI.
The socket, in outline:
- The client opens the socket and, within 10 seconds, sends
{"type": "hello", "token": "<session token>", "lastSeq": <number | null>, "protocolVersion": <n>}. - The server answers
readywith a snapshot of what the account can see and the current event sequence number. - If
lastSeqwas given, the events since then that the account may see follow aseventframes — with gaps, since events it may not see are skipped — and thensynced. If the log no longer reaches back that far,resynctells the client to discard what it has and reconnect withlastSeq: null. - From then on:
eventfor durable changes,ephemeralfor typing, presence and similar, andpongfor the client'sping.
The server closes the socket with 4000 for a malformed frame, 4002 for a protocol version it does not speak, 4003 for a session that is unknown, expired, signed out or revoked, and 4004 for an account that must choose a new password before it can continue.