Open a room and share a code
POST /matchmaking/games/duel/roomsA session is minted with the host already in it, and a code is returned. This is one of four ways in.
POST /matchmaking/rooms/WXYZ-1234/joinJoin tolerates lowercase, whitespace and a missing dash. The code’s alphabet already excludes I, O, 0 and 1.
Invite somebody directly
POST /matchmaking/games/duel/invites
{ "email": "ada@example.com" }Or a screen name — best-effort, because auth exposes no unique one. A name matching zero users or several is refused rather than guessed.
| Route | |
|---|---|
GET /matchmaking/invites | Pending, for the caller |
POST /matchmaking/invites/:id/accept | Mints the session and seats both |
POST /matchmaking/invites/:id/decline |
Exactly two players. A game with a larger roster is refused here and told to use a code or the queue. An invite is answered once: accepting or declining one that is already accepted, declined or canceled is matchmaking/invite_not_found, and nothing is minted for it.
Friends
The fourth way in is the waiting queue, which needs provisioning before it will pair anybody.
| Route | |
|---|---|
GET /matchmaking/friends | |
POST /matchmaking/friends/:userId/request | |
POST /matchmaking/friends/:userId/accept | Mutual accept forms the edge |
POST /matchmaking/friends/:userId/decline | |
DELETE /matchmaking/friends/:userId |
The routes mount only when friends is on — that flag, and every other, is in the reference.
Queue
POST /matchmaking/games/duel/queue
GET /matchmaking/games/duel/queue
DELETE /matchmaking/games/duel/queueA player learns they matched through presence, not by polling.
Presence
GET /matchmaking/presence (WebSocket)On connect: pending invites, and which friends are online now.
Then events as they happen — match_found, invite, friend_request, and, when a management client acts, invite_canceled and queue_dropped. Offer pithy.presence.v1 in Sec-WebSocket-Protocol, and a frame the socket cannot accept is answered with an error frame rather than ignored. The keepalive is a plain-text ping, answered with pong. The socket contract has every frame.
The identity is a server-set header from the authenticated handler, stashed so it survives eviction. The object never trusts a client-supplied user id.
Call it from a client
A web app the Worker serves calls these routes through @pithy-sh/matchmaking/src/client/api — createRoom, joinRoom, sendInvite, listInvites, acceptInvite, declineInvite, the friend calls, and joinQueue, readQueue and leaveQueue. presencePath gives it the presence socket’s path, and MATCHMAKING_PRESENCE_PROTOCOL the subprotocol to offer. It is same-origin by construction, and no call throws; each returns a result to render.
A mobile app or a game engine generates its HTTP client from the Worker’s openapi.json and reads the presence socket against its asyncapi.json, both written by pithy contract. The frames are Zod schemas in @pithy-sh/matchmaking/src/presence/frames.
Watch it from a dashboard
With the control plane composed, a management client reads who is waiting and acts on it. matchmaking:queues:read lists the configured games, each with the key the per-game routes take, and reads a game’s queue, from its queue object, its open rooms, and every pending invite. matchmaking:queues:moderate cancels a pending invite or drops a player from a queue, each with an idempotency key and a required reason. A cancel tells both players, and a drop tells the player why, over presence. Each act writes one audit event, and nothing here touches the friend graph. The reference has the routes.
Nothing here is a hard dependency
Each peer is reached through a seam, and its absence degrades one thing rather than breaking the composition:
| Absent | What happens |
|---|---|
| Auth | Every route denies. The right failure — a pairing layer with no identity has nothing to pair |
| Rating | The queue buckets by region only. No skill matching, everything else unchanged |
| Multiplayer | Every pairing path still runs, and none of them can mint the session it exists to produce |
Install them and it lights up, with no wiring.
Mount it elsewhere
basePath moves the whole surface. The friend routes follow it.
What it stores
pithy_matchmaking_invites | Direct invites, indexed by invitee, carrying the session id once accepted |
pithy_matchmaking_friends | One row per pair, indexed both ways |
KV, matchmaking:<code> | Room codes |
Room codes belong in KV rather than D1 because a room code is a short-lived pointer with a TTL and a use counter — which is exactly what KV is, and nothing else here is.
Queue state lives in the queue object’s own storage, and presence is the live socket set. Neither is a row you keep.