Inachess integration docs

Inachess is a realtime chess engine your platform plugs into: you keep auth, users and ratings; the engine runs every game. These docs follow the order you integrate in — read Start here top to bottom, then work through the guide.

The three actors

Every page in these docs involves the same three parties. Keep this picture in mind and every flow reads the same way:

Platformyou — auth · users · ratings · UI

REST /v1 →← callbacks

EngineInachess — authority over all game logic

WebSocket ⇄

Clientyour app + @inachess/sdk

Platform → Engine (REST) — synchronous requests you make: mint session tokens, list game types, create tournaments, serve puzzles, read history. Full REST reference →
Engine → Platform (callbacks) — asynchronous webhooks you receive: game results, aborts, tournament outcomes. Retried until acknowledged, deduped by eventId. Plus one pull in the other direction: the engine fetches GET /users/{userId} from you at enqueue. Callbacks guide →
Client → Engine (WebSocket) — one socket per login session, opened right after login. Queueing, playing, bot games and spectating all ride on it, via @inachess/sdk. Sessions guide →

The whole integration at a glance:

Platform→EnginePOST /v1/sessions at login → token handed to the clientreq
Client→EngineWS dial once — token in the subprotocol, one socket per sessionws
Client→Enginequeue · play_bot · subscribe — everything rides that socketws
Engine→PlatformGET /users/{userId} — the engine pulls detail + ratings at enqueuereq
Engine→Platformmatch_found · game_result · … — callbacks to your webhookcb
Platform→EngineGET /v1/matches/results?since= — reconciliation backstopreq

Rules that never bend

Four invariants shape every endpoint and message. If something in the API surprises you, it is almost always one of these at work:

UCIthe only move format, on every layer

msserver-authoritative clocks

No JWTone opaque session token per login

exactly-oncecallback effect (retry + idempotent)

The server is authoritative. Clients send intent only — the engine validates every move and computes every clock. A client can never set its own time, result, or rating.
UCI everywhere. Moves are UCI strings (e2e4) on the wire, in the DB, in callbacks, in reviews. Never SAN. UCI in full →
The platform owns identity and ratings. The engine computes rating changes but stores no canonical copy — game_result hands you the new rating to persist.
Delivery is exactly-once in effect. The engine retries callbacks until you acknowledge them (at-least-once); you dedupe by eventId (idempotent). Ratings are never lost, never double-applied.

How these docs are ordered

The guide follows the integration journey — each page builds on the previous one. The reference section is for lookup once you are building; the cookbook shows complete scenarios including every failure branch.

Start hereOverviewConcepts & termsQuickstart Integration guidePlatform setupSessions & connectionFinding a gamePlaying a gameCallbacks & reliabilityTournamentsPuzzles ReferenceREST APIWebSocket wireCallbacksSDKErrors & codes HelpUse casesFAQ

New to the project? Read Concepts & terms first — it defines every term these docs use, in plain language. Want running code immediately? Jump to the Quickstart.