Bots
Manage bots
Bots are tenant-owned identities that can be placed into the matchmaking pool or a specific session. Available for chess, checkers, connect4, and tictactoe.
/v1/botsRegisters a new bot for a game.
| Field | Type | Description | |
|---|---|---|---|
game | string | required | One of the four bot-supported games. |
name | string | required | Internal label shown in your dashboard. |
playerId | string | required | Must match an existing account ID in your own user system. |
displayName | string | required | Name shown to the human opponent in-game. |
botType | string | required | algorithmic or learned. |
difficulty | string | if algorithmic | easy · medium · hard. |
targetRating | number | if learned | 3, 4, or 5 — the grade the model is trained toward. |
matchmakingWeight | number | optional | Relative weight when several bots compete for a matchmaking fallback slot. Default 100. |
retrainThreshold | number | optional | Games played before a learned bot automatically retrains. Default 50. |
GET /v1/bots?game=chess
Lists active bots registered for a game.
GET /v1/bots/:id
Fetches a single bot by ID.
PATCH /v1/bots/:id
Updates any bot field — difficulty, weight, active state, and so on.
DELETE /v1/bots/:id
Deactivates a bot; it stops receiving matchmaking traffic.
Bot types
| Type | Behaviour |
|---|---|
algorithmic | Fixed-strength engine move at one of three difficulty presets. |
learned | A per-grade move policy trained from your own tenant's recorded games, refreshed automatically once gamesSinceRetrain passes retrainThreshold. |
Algorithmic difficulty presets (chess)
| Difficulty | Search depth | Behaviour |
|---|---|---|
| easy | 1 ply | ~30% random moves, occasional blunders, responds in 0.5–1.5s. |
| medium | 3 ply | ~15% suboptimal moves, responds in 1–3s. |
| hard | 4 ply | Always plays the best move found, responds in 2–5s. |
Add a bot to a session
/v1/sessions/:id/bots?game=chessDrops a bot into a specific pending session — either a named bot you registered, or, if you omit playerId, one the service picks for you by matchmaking weight. If the session's room is already open in memory, the bot is injected live via the socket layer so play can start immediately.
| Field | Type | Description | |
|---|---|---|---|
playerId | string | optional | Omit to let the service auto-select a bot by matchmakingWeight. |
displayName | string | optional | Used only alongside a manual playerId. |
botType | string | optional | Defaults to algorithmic for a manual bot. |
difficulty | string | optional | Defaults to medium for a manual bot. |
| Status | Meaning |
|---|---|
| 404 | Session not found, or (auto-pick) no active bots exist for that tenant + game. |
| 409 | Session isn't pending, the player is already in it, or the room is already full. |
Matchmaking fallback
Per game, you can configure how long the matchmaking queue waits for a human opponent before falling back to a bot.
GET /v1/bots/matchmaking-config?game=chess
Reads the current fallback configuration.
PATCH /v1/bots/matchmaking-config
Updates fallbackDelaySec and enabled for a game.
Request body — PATCH
{
"game": "chess",
"fallbackDelaySec": 20,
"enabled": true
}When a bot is selected for fallback, one is chosen from your active bot roster in proportion to each bot's matchmakingWeight — a bot with weight 200 is picked twice as often as one with weight 100.