Bot creation

Create and manage bots that automatically fill matchmaking queues when real players aren't available. Two bot types are supported: algorithmic (fixed difficulty) and learned (trained from real game data).

⚠

Chess learned bots are currently unstable

Learned bots for chess have known reliability issues and are not recommended for production use. Algorithmic chess bots (easy/medium/hard) work correctly. Avoid creating learned chess bots until further notice.

Bot types

Algorithmic

Uses the built-in minimax engine at a fixed difficulty level. No training required — ready immediately.

easymediumhard

Learned

Trained from your players' game records. Adapts to your player base over time. Requires a targetRating (3–5) and at least one training run.

3 ★4 ★5 ★

Create a bot

POST /api/v1/bots

Algorithmic bot

curl -X POST https://api.beta-gamer.com/api/v1/bots \
  -H "Authorization: Bearer bg_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "game":               "chess",
    "name":               "Easy Bot",
    "playerId":           "user_bot_chess_easy",
    "displayName":        "ChessBot",
    "botType":            "algorithmic",
    "difficulty":         "easy",
    "matchmakingWeight":  100
  }'

Learned bot

curl -X POST https://api.beta-gamer.com/api/v1/bots \
  -H "Authorization: Bearer bg_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "game":               "chess",
    "name":               "Adaptive Bot",
    "playerId":           "user_bot_chess_adaptive",
    "displayName":        "AdaptBot",
    "botType":            "learned",
    "targetRating":       4,
    "matchmakingWeight":  100,
    "retrainThreshold":   50
  }'

⚠️ playerId must match an existing account in your system. This prevents real users from registering with the same ID and impersonating a bot. Create a dedicated bot account in your user system first, then use its ID here.

Request fields

Field	Type	Required	Description
`game`	string	✓	chess, checkers, connect4, or tictactoe
`name`	string	✓	Internal label for this bot (not shown to players)
`playerId`	string	✓	ID of an existing account in your system — used as the bot's identity in games
`displayName`	string	✓	Name shown to opponents in-game
`botType`	string	✓	"algorithmic" or "learned"
`difficulty`	string	algorithmic only	"easy", "medium", or "hard"
`targetRating`	number	learned only	3, 4, or 5 — target skill level
`matchmakingWeight`	number	—	Relative probability of being selected (default 100)
`displayRating`	number	—	Optional 1–5 rating shown to players (overrides computed rating)
`retrainThreshold`	number	—	Games played before auto-retraining triggers (default 50)

Game-specific config

Each game supports different bot configuration options. Fields not applicable to a game are ignored.

Game	Algorithmic fields	Learned fields	Notes
`chess`	difficulty (easy/medium/hard)	targetRating, retrainThreshold	⚠ learned unstable
`checkers`	difficulty (easy/medium/hard)	targetRating, retrainThreshold	—
`connect4`	difficulty (easy/medium/hard)	targetRating, retrainThreshold	—
`tictactoe`	difficulty (easy/medium/hard)	targetRating, retrainThreshold	—

Manage bots

Method	Endpoint	Description
GET	/api/v1/bots?game=chess	List all active bots for a game
GET	/api/v1/bots/:id	Get a single bot
PATCH	/api/v1/bots/:id	Update name, weight, difficulty, rating, or active status
DELETE	/api/v1/bots/:id	Deactivate a bot (soft delete)

Matchmaking config

Controls when and how bots fill empty matchmaking slots. Configured per game.

# Get current config
curl "https://api.beta-gamer.com/api/v1/bots/matchmaking-config?game=chess" \
  -H "Authorization: Bearer bg_live_xxxx"

# Update config
curl -X PATCH https://api.beta-gamer.com/api/v1/bots/matchmaking-config \
  -H "Authorization: Bearer bg_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "game": "chess", "fallbackDelaySec": 20, "enabled": true }'

Field	Default	Description
`fallbackDelaySec`	15	Seconds to wait for a real opponent before pairing a bot
`enabled`	true	Whether bot fallback is active for this game

Training learned bots only

Learned bots improve by training on game records from your players. Training runs automatically when gamesSinceRetrain reaches retrainThreshold, or you can trigger it manually.

Manual training

curl -X POST https://api.beta-gamer.com/api/v1/bots/:id/train \
  -H "Authorization: Bearer bg_live_xxxx" \
  -d '{ "trigger": "manual" }'

Import PGN (chess only)

Seed a learned bot with existing game data by importing a PGN file. Supports multi-game PGN.

curl -X POST https://api.beta-gamer.com/api/v1/bots/:id/train \
  -H "Authorization: Bearer bg_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "trigger": "pgn_import", "pgn": "[Event \"Game 1\"]\n\n1. e4 e5 2. Nf3 ..." }'

Challenge (bot vs bot)

Simulate games between two of your bots to generate training data without real players. Both bots are retrained after the challenge completes.

curl -X POST https://api.beta-gamer.com/api/v1/bots/:id/challenge \
  -H "Authorization: Bearer bg_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "opponentBotId": "bot_abc123", "games": 50 }'

games — number of simulated games (default 10, max 100). Omit opponentBotId to challenge the bot against itself.

Matchmaking weight

When multiple bots are active for a game, the platform picks one using weighted random selection. A bot with weight 200 is twice as likely to be selected as one with weight 100.

// Two bots — easy is selected ~33% of the time, hard ~67%
{ "name": "Easy Bot", "matchmakingWeight": 100 }
{ "name": "Hard Bot", "matchmakingWeight": 200 }

Beta Gamer GaaS API — questions? support@beta-gamer.com