Bot API documentation

Base URL https://apigaming.com/v1, JSON only. Bots pull: they poll one long-poll endpoint, post moves with a sequence number and never need an inbound port.

Contract: OpenAPI. For an AI agent: /agents.md (the whole guide in one file) and /llms.txt. Sample bots: Starter bots.

Each part as Markdown, for an AI to read: /docs/api.md (this page's API reference), /docs/tournaments.md, /docs/browser-bots.md.

Conventions

• Auth: Authorization: Bearer ag_.... Unauthenticated: the catalogue and the HTML board.
• snake_case fields. IDs are opaque prefixed strings: usr_, bot_, key_, ch_, set_, m_. Timestamps ISO 8601 UTC with ms. Durations are integer ms with suffix _ms. Money is {"amount": <int points>, "currency": "PTS"}; amounts are whole points.
• Every response carries server_time. Lists return {"data": [...], "next_cursor": null|string}; limit 1-200, default 50.
• Types are strict: 3.0, "3", true are never accepted where an integer is expected. Unknown request fields and bodies over 16 KB (64 KB for moves) are rejected with 400.
• Seats are 1 and 2. to_move is the list of seats on move; read it rather than assume seat 1 opens (a Fourfall opening with an odd number of discs leaves seat 2 on move). A set is two matches from the same opening with the seats swapped (one game for single-pairing engines).
• Long-poll: wait_ms 0-25000. GET /v1/matches/{id} returns at once when the match is not active, when you are on move, or when since is given and move_number > since; on timeout it returns 200 with the current state.
• Rate limits: per key 50 req/s (burst 100), per user 150 req/s (burst 300), moves 50 req/s per match (bots are never paced, only runaway loops are stopped), at most 4 concurrent long-polls per key; RateLimit headers and Retry-After on 429.

Your first game

1. Sign up on the website (you can play at once; verifying the email, later, enables password reset).
2. Create a bot on /account.
3. Create an API key with scope play; it is shown once.
4. POST /v1/faucet for the account's 1,000 points of the day (the hello-world below does this), or claim them into the wallet on /account and move them to your bots.
5. Run the hello-world; a house bot always has one challenge open per game.

Endpoints

Move formats

Each game has its own move shape, set out on its page and machine-readable at GET /v1/games/{game_type}.

• Fourfall fourfall
• Breakthrough breakthrough
• Hex hex
• Racetrack racetrack
• Travelling salesman duel tsp_duel
• Twist Cube twist_cube
• Snooker snooker
• Bitcoin Trader btc_trader
• Tictactoe (not loaded on this instance) tictactoe
• Polyfit polyfit

Errors

Hello-world bot

Standard library only. Set BASE to https://apigaming.com/v1 when running against this deployment and KEY to your ag_ key.

import json, uuid, urllib.request, urllib.error
BASE, KEY = "https://api.apigaming.com/v1", "ag_xxx"

def call(method, path, body=None, extra=None):
    hdr = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json", **(extra or {})}
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(BASE + path, data=data, method=method, headers=hdr)
    with urllib.request.urlopen(req, timeout=35) as r:
        return json.load(r)

try:
    call("POST", "/faucet")
except urllib.error.HTTPError as e:
    if e.code != 409:
        raise

found = call("GET", "/challenges?game_type=fourfall&max_stake=25&limit=1")["data"]
if found:
    call("POST", f"/challenges/{found[0]['id']}/accept")
else:
    call("POST", "/challenges", {"game_type": "fourfall", "stake": {"amount": 20, "currency": "PTS"}},
         {"Idempotency-Key": str(uuid.uuid4())})

while True:
    mine = call("GET", "/matches?status=active&to_move=me&wait_ms=25000")["data"]
    if not mine and not call("GET", "/matches?status=active")["data"]:
        break                                   # both games of the set are over
    for match in mine:                          # a set is two boards; play every one waiting on us
        try:
            call("POST", f"/matches/{match['id']}/moves",
                 {"move_number": match["move_number"] + 1, "move": match["legal_moves"][0]})
        except urllib.error.HTTPError as e:
            print(json.load(e)["code"])         # the next poll resyncs the state

print(call("GET", "/matches?status=finished&limit=1")["data"][0]["set"]["result"])

Tournaments

Scheduled events where the whole field plays one table of a game at the same time, for a prize in points. Free to enter; the bot itself checks in through the API. As Markdown

What a tournament is

• The operator schedules tournaments, once or daily, of the games played in parallel: Bitcoin Trader btc_trader, Polyfit polyfit, Polyfit 3D polyfit3d, Racetrack racetrack, Travelling salesman duel tsp_duel, Twist Cube twist_cube.
• Every bot that is seated plays the same one table, on the same instance of the game, at the same time. The best score takes the prize.
• Entering is free: nothing is staked or escrowed, and the tournament's own table is not rated.
• Each tournament is for one tier of bots, by the bot's Elo rating in that game (1200 until it has one): beginner: rated 1299 or lower; medium: rated 1300 to 1599; pro: rated 1600 or higher. A bot outside the band cannot register, and the band is checked again at the start.
• Find them on the website at /tournaments, or with GET /v1/tournaments?status=upcoming (also live and finished).

Timeline

• scheduled, then registration_open from registration_opens_at, then checkin_open from checkin_opens_at (by default 30 minutes before the start), running from starts_at, and finished.
• It is cancelled instead when the operator cancels it, or when fewer than min_entrants bots are ready at the start.
• Every time is the server's: compare with server_time, or use ms_to_start.

Entering with your bot

• Register on the website (the tournament's page) or with POST /v1/tournaments/{id}/register and the bot's play key. When every place is taken the bot joins the waitlist instead. Withdraw with DELETE /v1/tournaments/{id}/register.
• Check-in and pings are API-only, made by the bot itself with its play key: POST /v1/tournaments/{id}/checkin once check-in opens, then GET /v1/tournaments/{id}/ping at least every 60 s until the start. Every answer carries ready and ready_until.
• The simplest way: the Python client does all of it. python -m bots.client <your bot module> --tournament <tournament id> registers (or joins the waitlist), checks in when the window opens, pings until the start and then plays the table like any other match.
• A bot running in your browser (Run in browser, below) does not check in to tournaments: for a tournament, run the bot on your computer or a VPS with the command above.

The start

• At starts_at the registered bots that are ready take a seat, in check-in order; free seats then go to ready bots on the waitlist, in check-in order.
• Ready means checked in and seen in the last 2 minutes. Losing the connection before the start costs nothing: be seen again (a ping, or any call with the key) and the bot is ready again. Only the moment of the start counts.
• Your entry's you.outcome says what happened: seated, seated_from_waitlist, waitlist_not_needed, not_checked_in, not_connected, not_eligible, out_of_tier or withdrawn.
• The table is an ordinary match: it appears in GET /v1/matches?status=active&to_move=me and is played with the usual moves and clocks. A seat that misses its first move is out and ranks last.

Results and the prize

• The leaderboard is live while the table plays and final once it has finished: on the tournament's page, or GET /v1/tournaments/{id}/leaderboard.
• The prize goes to first place, into the bot's available points. A shared first place goes to the game's tiebreak where it has one; bots still level split the prize.

When something goes wrong

• Not seated: read you.outcome. not_connected means the bot was not seen in the 2 minutes before the start: ping every 60 s. not_checked_in means it never called check-in.
• 403 tier_ineligible: the bot's rating is outside the tournament's tier. 409 tournament_full: the places and the waitlist are taken. 409 registration_closed or checkin_closed: outside that window.

Run a bot in your browser

Play a bot from a web page, in Python, with nothing to install: on a computer, on a phone, or in the installed app. As Markdown

What it is

• Run in browser runs your bot's Python code in the page itself (Pyodide, Python built for the browser). It plays through the same public API as any bot, with its own play key.
• Use the ready-made bot for a game (the same file as that game's starter bot on /starter), or your own file.

Starting a bot

• Sign in and open My bots (/bots, a tab at the foot of the screen on a phone): every bot of the account (up to 10), each with Start and Stop, and Start all and Stop all. A bot's own page has the same controls for that bot on its Run in browser tab.
• Tick the games the bot should play: one chip per enabled game. A greyed-out game cannot run in the browser, and the reason is shown.
• For each game, choose the code: the ready-made bot, or your own Python file.
• On a bot's Run in browser tab, choose what it plays first: nobody yet (it connects and waits; take or post a challenge with it in the Lobby and it plays), the house at level 1, 2 or 3 (free practice), or another bot in the lobby (10 points at stake). Practice and the lobby play the first ticked game.
• Press Start. The first Start makes a play key for the browser. The page keeps it in memory: it is never shown, saved or put in a link. Starting again later makes a new one, which stops the bot wherever it ran in a browser before.

Auto-play and the Lobby

• While a bot runs it tells the server which games it can play now (POST /v1/me/ready, every 30 s; it lapses 90 s after the last one). The Lobby then offers Take with <bot> in one tap.
• Auto-play, a switch per game, lets the server start lobby sets for the bot on its own: it keeps one quick-match seek for the bot at the default stake (50 points, within the game's limits and the bot's maximum stake). Each set stakes the bot's points. It plays one set of a game at a time and stops within seconds of Stop, or of the page closing.

Your own bot file

• One Python file: .py, or .txt with Python in it (a phone may only save .txt), up to 200 KB.
• It defines GAME_TYPE, the game it plays (such as "fourfall"), and choose(match, deadline), which returns the move as a dict, or None when it has nothing to post yet. match is the object GET /v1/matches/{id} returns; deadline is a time.monotonic() value to answer by. This is the same contract as python -m bots.client, so one file runs in the browser and on a computer alike.
• Name the file after your bot, not after a standard module such as random.py or json.py.
• It may use the Python standard library, except the modules a browser cannot run: _thread, asyncio, concurrent, ctypes, curses, dbm, ensurepip, fcntl, idlelib, lzma, mmap, multiprocessing, pty, readline, resource, select, selectors, signal, socket, sqlite3, ssl, subprocess, termios, threading, tkinter, tty, turtle, venv, webbrowser.
• The file stays in this browser (local storage) and is never uploaded. Another browser or device needs it picked again.

How long it keeps playing

• In a browser tab the bot plays while the tab stays open. Reload or close the page and it disconnects, and a game in progress is lost on time; the page asks before you leave while bots play.
• In the installed app the bot keeps playing while you move around apigaming and stops when the app closes. A phone may pause it while the app is in the background.
• In turn-based games the runner waits a moment before each move so the log and the board can be followed. In games played in parallel (the race games) it posts at once.
• To keep a bot playing all the time, or to enter a tournament, run it on a computer or a VPS: the Run in browser tab offers the bot as a .zip and the command to run it.

Safety

• The bot's code runs in a sandboxed frame: no cookies, no storage and no access to your session or the page. It can only call apigaming's API, with the bot's own key.