Training Grounds API
For owners who want their reports in their own tools, and for developers training their own bots on Training Grounds. Needs Training Grounds on your account. Base URL: https://api.botlands.org/training/v1.
Keys
Make keys on your keys page. A key looks like blt_xxxxxxxxxxxx_..., is shown once, and is sent as Authorization: Bearer <key>. Give each key only the scopes it needs. Revoke a key there at any time; it stops working at once.
| scope | lets the key |
|---|---|
reports:read | read your drill reports, sessions and ladder place |
drills:run | queue drills for your bot on the training server |
dataset:read | download the decision points your bot was coached on |
loop | bot in the loop: coach and grade your own bot while you are on Training Grounds |
Endpoints
| call | scope | what |
|---|---|---|
GET /training/v1/me | any | your key, access, quotas used today, and whether you are on Training Grounds now |
GET /training/v1/drills | any | the drill catalog |
POST /training/v1/sessions | drills:run | {"drill":"crystal","level":3,"rounds":2} queues drills for your bot (at most 3 waiting) |
GET /training/v1/sessions | reports:read | your sessions, newest first (?limit=) |
GET /training/v1/sessions/<id> | reports:read | one session and its report ids |
POST /training/v1/sessions/<id>/cancel | drills:run | cancel a session that has not started |
GET /training/v1/reports | reports:read | your reports (?limit=&before=&drill=) |
GET /training/v1/reports/<id> | reports:read | one report |
GET /training/v1/dataset | dataset:read | the decision points your bot was coached on: senses, legal moves, its move and the right one (?limit=&before=) |
POST /training/v1/coach | loop | {"drill","f":{...},"legal":[...]}: the coach's move for one decision, or null |
POST /training/v1/grade | loop | {"drill","steps":[{"f","legal","a","r"}]}: grade up to 400 decisions |
GET /training/v1/ladder/me | reports:read | your bot's ladder rating and rank |
Rules of the road
- Every
POSTneedscontent-type: application/json,x-bl-timestamp(now, in ms) andx-bl-nonce(16 to 64 ofA-Z a-z 0-9 _ -, new for every request). A repeated nonce is refused. - Bodies are checked strictly: unknown fields, unknown senses or moves, and values outside -1 to 1 are refused. Senses are the bot's situation only (health, supplies, distances scaled to 0..1); there is no field for coordinates.
/coachand/gradework only while your account is on Training Grounds.- Limits per key and per address, with short bursts allowed, plus daily quotas (see
GET /me). Over a limit you get429withretry-after. Many refused requests in a few minutes lock the key or the address for an hour (423). This only affects the API. - You only ever see your own bot's data.