API reference

WebSocket

One connection per client carries requests, answers and server pushes as JSON objects in text frames. Binary frames are not part of the protocol and are ignored.

wss://your-server.example/v1/ws

The envelope#

Rules:

• id is an unsigned integer you choose (a counter per connection is enough), echoed unchanged in the answer. Every request gets exactly one answer. Answers to different requests arrive in the order the requests were sent (one socket's requests are handled one after another).
• data may be left out (it then means null). In an answer, a missing ok means true and a missing data means null.
• Telling frames apart: a frame with a numeric id and (an ok field or no type) is an answer. Anything else with a type is a push or an auth result (auth.ok, auth.failed). A push never has an id or ok field.
• A malformed frame that has an unsigned-integer id is answered bad_request; one without a usable id cannot be answered and is dropped.
• Request errors: bad_request (malformed frame or data), unauthorized (not authenticated yet), unknown_type, rate_limited (details.retry_after_ms), payload_too_large (the answer would exceed the message limit), unavailable (the handler took longer than 10 s), internal, plus each kind's own codes.

Connecting and authenticating#

• Without a header the upgrade succeeds anonymously; the socket must send auth within 5 seconds. Requests sent before auth.ok are answered unauthorized, and pushes only reach authenticated sockets. Wait for auth.ok before sending requests.
• Every auth message gets exactly one auth.ok or auth.failed, also on a socket the handshake header already authenticated.
• A later auth with a fresh token of the same user re-authenticates an open socket (answered auth.ok); a token of another user is refused (auth.failed, close 4001).
• auth.failed is final for that socket: the server closes it right after (4001; 4003 when banned; 4010 for an unsupported protocol). Its error.code says why (token_expired, unauthorized, banned, unsupported_protocol).
• A temporary server failure while checking auth (database down, overload) closes with 1013 without auth.failed: reconnect with backoff and try again.
• An open socket survives the expiry of its access token. Only a revocation closes it (logout, password change or reset, admin action, refresh-token reuse: 4001; a ban: 4003). Re-sending auth with a fresh token is not required.

Handshake answers (HTTP, before the upgrade):

The endpoint never answers 400. Note that a browser does not show the status of a refused handshake (the WebSocket just closes with code 1006); with first-message auth the reason arrives as auth.failed instead.

Version mismatch#

Name your version in the x-net-backend-protocol handshake header or the protocol field of auth. An unsupported version: the server upgrades, then closes with 4010 (with first-message auth: auth.failed unsupported_protocol + 4010). A non-upgrade request with an unsupported version gets 403. Do not reconnect; the client needs an update.

Heartbeats#

The server sends a WebSocket ping every 20 s and answers the client's pings. A connection that sent nothing (not even a pong) for 60 s is dropped. Browsers and most libraries answer pings automatically. Clients may send their own pings (they count against the frame rate).

Close codes#

Never reconnect automatically after 4000–4099. The server uses that range only for "do not come back with these credentials". For 4001: refresh the tokens once; if the refresh succeeds, connect once more with the new access token; if the refresh fails (or the new connection gets 4001 again), show the login screen. For 4009: tell the player another window or device took over; reconnect only on a user action.

For every other code, reconnect with exponential backoff and jitter (for example 1 s, 2 s, 4 s, … up to 30 s, each ±25 %); reset the backoff after auth.ok. After a reconnect: authenticate again, join your chat rooms again (membership ends with the connection) and reload anything you may have missed (chat history newer than your last message, storage objects).

Kinds registered by the reference server#

A game's own server may register more kinds; its /v1/asyncapi.json lists them all. An unknown request kind is answered unknown_type; ignore push kinds you do not know.

Chat kinds in detail#

• chat.join — by room id ({"room":12}) or a public room's key ({"room":"world"}). Joining a room already joined is not an error. Membership lasts as long as the connection. Group rooms need membership; DM rooms need no join (joining answers their info). Errors: not_found, not_a_member, room_full (the room's cap counts connections), quota_exceeded (16 rooms on this connection), validation_failed (an invalid key).
• chat.leave — leaving a room not joined is not an error.
• chat.send — to a room joined on this connection, or to one of your DM rooms (no join needed). The answer {"message_id","sent_at"} comes before your own chat.message echo. Dedupe by message_id (answer) = id (push), or match the nonce. The text in the push is the final text after server rules (it may differ from what you sent). Errors: validation_failed (text rules), rate_limited (details.retry_after_ms, about 2000 right after a burst), not_a_member, or a server rule's refusal (for example forbidden from a word filter).
• chat.history — the same as the HTTP history route, over the socket. Public rooms: anyone; group and DM rooms: their members.
• chat.members — who is online in a room joined on this connection, each user once, up to 200 listed (truncated: true when cut), count = the total. A DM room lists only the caller: a DM never reveals whether the other player is online.
• chat.message — to every member connection of the room, the sender's included (also the sender's other devices). A DM's message goes to every open connection of both users, joined or not. The nonce: in public and group rooms every member's push carries it (use a random value, never anything secret); in DMs and in the history only the sender sees it.
• chat.deleted — a message was deleted (moderation or its sender); remove it from the screen.
• chat.presence — joined when a user's first connection joins the room, left when their last one leaves or disconnects; count is the room's online users after the change. Your own connections get it too. Best effort: rooms with more than 100 online users get none, and each room pushes at most 10 per second; chat.members always answers the full list.

Generated from API.md (repository commit e25edb9, file sha256 3db87f7bba70).