Sessions

Create a session

POST/v1/sessions

Creates a new session for one of the six documented games. Returns a short-lived session token for your client.

Body parameters

Field	Type		Description
`game`	string	required	checkers · tictactoe · connect4 · fight-arena · pool · ludo
`mode`	string	optional	Defaults to live for a live key, test for a test key. Test keys cannot request live.
`matchType`	string	optional	matchmaking (default) · private · bot — see Hosted Matchmaking for the separate ticket-based flow.
`players`	array	live / test	Array of { id, displayName }. Required for every mode except training.
`playerCount`	number	training only	How many anonymous players to generate.
`platform`	string	optional	android or ios — triggers a device integrity check if a credential exists.
`integrityToken`	string	optional	Attestation token from the platform's integrity SDK.

Want your own backend to explicitly assemble a match — pairing specific players together rather than an auto-queue — instead of a simple matchType value here? That's a separate, ticket-based flow under /v1/matchmaking/hosted/*, documented on its own once that section ships. It is not a value you pass to this endpoint directly.

Response — 201

Field	Type	Description
`sessionId`	string	Unique session identifier.
`sessionToken`	string (JWT)	Hand this to the client. Expires in expiresIn seconds (300).
`roomCode`	string \| null	Present only for private match types — share it with the second player.
`theme`	object	Your tenant’s embed theme (colours, logo, font) so the client can render on-brand.
`webhooksEnabled`	boolean	true only when mode is live.

Match types

matchmaking

Default. The player is placed in your tenant's queue and paired by rating when an opponent is available.

bot

Pass one player; the second seat is filled by a bot.

private

Pass the host only. A roomCode is returned; the second player calls /v1/sessions/join with that code.

Retrieve a session

GET/v1/sessions/:id?game=checkers

Fetches a single session, including its result once the game has ended. Requires the same tenant that created it.

Field	Location		Description
`id`	path	required	The sessionId from creation.
`game`	query	required	Sessions are sharded per game table — this tells the API where to look.

Response — 200

json

{
  "id": "a1b2c3d4-...",
  "tenantId": "t_9c21...",
  "game": "checkers",
  "mode": "live",
  "matchType": "matchmaking",
  "status": "ended",     // pending | active | ended
  "players": [ /* SessionPlayer[] */ ],
  "result": { /* GameResult, see each game's own page */ },
  "createdAt": "2026-06-02T14:00:00Z",
  "endedAt": "2026-06-02T14:11:32Z"
}

Join a private room

POST/v1/sessions/join

Adds a second player to a private session using its room code, and returns a fresh session token for the joiner.

Field	Type		Description
`roomCode`	string	required	Returned from session creation.
`game`	string	required	Must match the room's game.
`player.id`	string	required	Joining player's own user ID.
`player.displayName`	string	optional	Defaults to player.id if omitted.

A player.joined webhook fires (live mode only) and the response mirrors the session-creation shape, with the updated players array.

Validate a token

GET/v1/sessions/validate?token=…

Unauthenticated lookup used by embed clients to confirm session status directly from a (possibly expired) session token — no API key needed, since the token itself proves knowledge of the session.

json

{
  "status": "ended",
  "game": "checkers",
  "result": { /* GameResult */ }
}

← Previous

Raw Socket Client

AFK Timeout Config