Docs / Integration API contract

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:

  1. The client opens the socket and, within 10 seconds, sends {"type": "hello", "token": "<session token>", "lastSeq": <number | null>, "protocolVersion": <n>}.
  2. The server answers ready with a snapshot of what the account can see and the current event sequence number.
  3. If lastSeq was given, the events since then that the account may see follow as event frames — with gaps, since events it may not see are skipped — and then synced. If the log no longer reaches back that far, resync tells the client to discard what it has and reconnect with lastSeq: null.
  4. From then on: event for durable changes, ephemeral for typing, presence and similar, and pong for the client's ping.

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.

This page is made from docs/INTEGRATIONS.md.