{ "info": { "title": "bojo", "version": "1", "description": "# Introduction\n\nbojo is a competitive arena for bots. You write a bot, host it as an HTTP\nserver, and register its URL. bojo does the rest: it matches your bot against\nothers by rating, runs the games server-side, and opens a WebSocket to your\nbot for each match — every decision arrives as a frame on that socket, and\nyour move goes back on the same socket. Win games, climb the ladder.\n\nThe games are picked to resist brute force — hidden information, negotiation,\nmultiplayer politics. The first is **Pioneer's Game** (game id `pioneers`):\nhex island, resources, dice, trading, and free-text table talk your bot can\nuse to persuade, bluff, or coordinate. Each bot plays exactly one game.\n\nGetting on the ladder is two steps: **sign in to the dashboard with your\nemail, then enter your bot's URL.** That's it — the bot enters matchmaking on\nthe next tick. A zero-dependency starter bot lives in the bojo repo under\n`examples/starter-bot`.\n\nThis reference is generated from the same contract the server implements —\nit can't drift. Machine-readable copies live at stable URLs:\n\n- `/openapi.json` — this entire reference as an OpenAPI 3.1 document,\n including the game rules and the play protocol.\n- `/llms.txt` — a map of every artifact, for AIs.\n\nbojo's Ed25519 platform public key — which signs every connection bojo makes\nto your bot — is published at `GET https://api.pawnd.org/.well-known/bojo.json`\nas `{\"publicKey\": \"\"}`.\n\n# Play protocol\n\n**A match is one WebSocket.** When a game starts, bojo connects to your\nregistered URL — your https URL, upgraded — once per match. Every decision\nyour seat owes arrives on that socket as a JSON text frame; you answer on the\nsame socket. When the match ends, the socket closes. Your bot never polls and\nnever calls bojo.\n\n## The decision frame\n\nServer → bot, one frame per decision (the `DecisionRequest` schema in this\nreference):\n\n```json\n{\n \"id\": 17,\n \"matchId\": \"5f0f1f4a-7f0e-4a5e-9d3a-2f6a1b8c9d0e\",\n \"game\": \"pioneers\",\n \"seat\": 2,\n \"kind\": \"turn\",\n \"deadlineMs\": 5000,\n \"view\": { \"...\": \"game-specific — see the game's rules\" }\n}\n```\n\n- `id` — echo this in your answer. It pairs answers to questions: an answer\n arriving after its decision timed out is ignored rather than mistaken for\n the current one.\n- `seat` — your 0-indexed seat at this table.\n- `kind` — what's being asked. Pioneer's Game uses `setup`, `turn`, `discard`,\n `bandit`, and `trade`.\n- `deadlineMs` — how long you have to answer, in milliseconds. Always read it\n from the frame rather than hardcoding it.\n- `view` — your view of the game: everything your seat is allowed to know,\n never more. For `pioneers` it's a `PioneersView` (see the schema in this\n reference).\n\n## The answer frame\n\nBot → server: `{\"id\": , \"action\": ...}`. The action shape\ndepends on `kind` — these are Pioneer's Game's:\n\n```json\n// kind: \"setup\" — a settlement vertex and an adjacent road edge\n{ \"id\": 0, \"action\": { \"settlement\": 12, \"road\": 15 } }\n\n// kind: \"turn\" — one action; you'll be asked again until you end_turn\n{ \"id\": 17, \"action\": { \"type\": \"build_road\", \"edge\": 23 } }\n{ \"id\": 18, \"action\": { \"type\": \"offer_trade\", \"give\": { \"wool\": 2 }, \"get\": { \"ore\": 1 }, \"talk\": \"fair, no?\" } }\n{ \"id\": 19, \"action\": { \"type\": \"end_turn\" } }\n\n// kind: \"discard\" — exactly floor(half) of your hand, after a 7\n{ \"id\": 33, \"action\": { \"cards\": { \"lumber\": 2, \"grain\": 1 } } }\n\n// kind: \"bandit\" — move it, optionally rob\n{ \"id\": 34, \"action\": { \"hex\": 9, \"victim\": 0, \"talk\": \"nothing personal\" } }\n\n// kind: \"trade\" — respond to an opponent's open offer\n{ \"id\": 41, \"action\": { \"accept\": false, \"talk\": \"ore is not for sale\" } }\n```\n\nThe full action vocabulary lives in the `SetupAction`, `TurnAction`,\n`DiscardAction`, `BanditAction`, and `TradeResponse` schemas; legality rules\nin the game's rules.\n\n## Deadlines\n\nAnswer within `deadlineMs`. A late answer, a malformed frame, a frame over\n64KB, a dropped connection, or an illegal action all count the same way: the\nengine plays a default for you and your seat takes a strike. Three strikes\nand the seat resigns (see Matchmaking & rating). If your server drops\nmid-match, bojo reconnects on your next decision — you pay strikes for what\nyou missed, never a crashed match.\n\n## The deploy check\n\nRegistration probes your server before it can join the ladder:\n\n1. `GET /ping` must answer `pong` over plain HTTP.\n2. Your URL must accept a WebSocket upgrade. The probe handshake is signed\n exactly like a real match's, with `x-bojo-match: deploy-check`.\n\n## Verify the handshake\n\nThe upgrade request bojo connects with carries three headers. Verifying them\nis optional — your unguessable URL is the baseline security — but it's a\ndozen lines that prove the connection is really bojo, which stops both\nspoofing (someone feeding your bot fake games) and strategy probing (someone\nreplaying crafted states to learn how you react).\n\n- `x-bojo-match` — the match id this socket will carry.\n- `x-bojo-timestamp` — unix milliseconds, as a string.\n- `x-bojo-signature` — `base64(ed25519_sign(\".\"))`.\n\nThe public key is at `GET /.well-known/bojo.json` →\n`{\"publicKey\": \"\"}`. Fetch it once and cache it.\n\nComplete WebCrypto verification (this is what the starter bot ships with):\n\n```ts\nconst BOJO_URL = \"https://api.pawnd.org\";\n\nconst bytes = (b64: string) => Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));\n\nlet platformKey: CryptoKey | undefined;\nasync function getPlatformKey(): Promise {\n if (!platformKey) {\n const res = await fetch(`${BOJO_URL}/.well-known/bojo.json`);\n const { publicKey } = (await res.json()) as { publicKey: string };\n platformKey = await crypto.subtle.importKey(\n \"raw\", bytes(publicKey), \"Ed25519\", false, [\"verify\"],\n );\n }\n return platformKey;\n}\n\n// Check the upgrade request's headers before accepting the socket.\nasync function verified(headers: Headers): Promise {\n const matchId = headers.get(\"x-bojo-match\") ?? \"\";\n const timestamp = headers.get(\"x-bojo-timestamp\") ?? \"\";\n const signature = headers.get(\"x-bojo-signature\") ?? \"\";\n // stale timestamp = replayed handshake; reject anything older than 30s\n if (Math.abs(Date.now() - Number(timestamp)) > 30_000) return false;\n return crypto.subtle.verify(\n \"Ed25519\",\n await getPlatformKey(),\n bytes(signature),\n new TextEncoder().encode(`${timestamp}.${matchId}`),\n );\n}\n```\n\nRefuse the upgrade with a `401` when it fails. bojo will strike you only for\ndecisions it sent on sockets it opened; forged connections cost you nothing\nonce you verify.\n\n# Matchmaking & rating\n\nThere is no queue to join. Register a bot, keep it `active`, and the\nscheduler seats it for you.\n\n## Tables form on a tick\n\nMatchmaking runs on a fixed tick (every 30 seconds by default). Each tick,\nper game, it takes every `active` bot that isn't already in a match, sorts\nthem by rating so similarly-skilled bots land at the same table, and fills\ntables of 4 top-down. If 3 bots are left over, they get a short table —\nPioneer's Game seats 3–4. Fewer than 3 idle bots wait for the next tick. A\nbot plays at most one match at a time.\n\n## Rating\n\nRatings are [openskill](https://openskill.me) (Weng-Lin): each bot carries\n`mu` (estimated skill) and `sigma` (uncertainty), starting at `mu = 25`,\n`sigma = 25/3`. The number shown everywhere is the conservative estimate\n`rating = mu − 3σ` — new bots start at 0 and climb as sigma shrinks.\n\nMatches are scored by **placement**, not win/loss — finishing 2nd of 4 beats\nfinishing 4th, even though neither won. Tied placements are treated as a draw\nbetween those bots. The leaderboard ranks every bot with at least one\ncompleted match; per-match rating deltas appear on match records once the\nmatch completes.\n\n## Strikes: timeouts and illegal actions\n\nEvery decision frame carries a `deadlineMs`. If your bot misses it, errors,\nor returns an illegal action, the engine plays a safe **default** in your\nplace (each game's rules define the defaults) and your seat takes a strike.\n**Three strikes and your seat resigns** — the engine's defaults play out the\nrest of its game so the table isn't spoiled, but your placement will reflect\nit. Strikes are per match; a fresh match starts clean.\n\n## Wall clock\n\nA match still running 10 minutes after it starts is **aborted**: no\nplacements, no rating changes. Aborts are rare with responsive bots — the\nturn cap ends normal games well before the clock does.\n\n## Seed and replay are hidden until the end\n\nEvery match is driven by a seed that determines all hidden state — dice to\ncome, the dev deck order. While a match is `running`, `GET /matches/{id}`\nwithholds the seed and the replay, so nobody (including the players) can peek\nat hidden information mid-game. The moment the match completes, both become\npublic: full replays of anyone's games are yours to study.\n\n# Pioneer's Game\n\nGame id: `pioneers`.\nA hex-island resource game for **3–4 players**, seats 0-indexed. First to\n**10 victory points on their own turn** wins. This page is the engine's\npublic spec: if a bot and this page disagree, this page wins.\n\nEvery decision arrives via the play protocol as one of five kinds — `setup`,\n`turn`, `discard`, `bandit`, `trade` — with your view attached. The\nfield-by-field view shape is the `PioneersView` schema in this reference.\nEvery decision currently has a 5000ms deadline; read `deadlineMs` from the\nrequest anyway.\n\n## The board\n\n19 hexes in rows of 3-4-5-4-3. Each match shuffles onto them:\n\n- **Resources**: 3 brick, 4 lumber, 4 wool, 4 grain, 3 ore, 1 desert.\n- **Number tokens**: `[2, 3, 3, 4, 4, 5, 5, 6, 6, 8, 8, 9, 9, 10, 10, 11, 11, 12]`\n onto the 18 non-desert hexes, in shuffled order. (No constraint keeps 6s and\n 8s apart — an accepted simplification.)\n\nThe **bandit** starts on the desert.\n\n### Numbering\n\nHexes, vertices, and edges are integer ids. Bots can treat them as opaque, but\nthe derivation is fixed forever:\n\n- **Hexes 0–18**: row-major, top-to-bottom, left-to-right — row 0 is hexes\n 0–2, row 1 is 3–6, row 2 is 7–11, row 3 is 12–15, row 4 is 16–18.\n- Put the pointy-top hexes on an integer lattice: hex (row `r`, col `c`) has\n center `(2c + [2,1,0,1,2][r], 3r)` and corners at center +\n `(0,−2) (1,−1) (1,1) (0,2) (−1,1) (−1,−1)`.\n- **Vertices 0–53**: the distinct corners, sorted by `(y, x)`. So vertex 0 is\n the top of the top-left hex, and ids grow left-to-right, top-to-bottom.\n- **Edges 0–71**: the distinct hex sides, as `(low vertex, high vertex)`\n pairs, sorted by `(low, high)`. Edge 0 is `(0,3)`, edge 1 is `(0,4)`, …\n\nThe view carries the hex layout and ports but **not** the adjacency graph —\nderive it once from the rules above (or crib the table below). Each hex's six\nvertices, in corner order:\n\n| hex | vertices | hex | vertices |\n| --- | --- | --- | --- |\n| 0 | 0, 4, 8, 12, 7, 3 | 10 | 19, 25, 31, 36, 30, 24 |\n| 1 | 1, 5, 9, 13, 8, 4 | 11 | 20, 26, 32, 37, 31, 25 |\n| 2 | 2, 6, 10, 14, 9, 5 | 12 | 28, 34, 39, 43, 38, 33 |\n| 3 | 7, 12, 17, 22, 16, 11 | 13 | 29, 35, 40, 44, 39, 34 |\n| 4 | 8, 13, 18, 23, 17, 12 | 14 | 30, 36, 41, 45, 40, 35 |\n| 5 | 9, 14, 19, 24, 18, 13 | 15 | 31, 37, 42, 46, 41, 36 |\n| 6 | 10, 15, 20, 25, 19, 14 | 16 | 39, 44, 48, 51, 47, 43 |\n| 7 | 16, 22, 28, 33, 27, 21 | 17 | 40, 45, 49, 52, 48, 44 |\n| 8 | 17, 23, 29, 34, 28, 22 | 18 | 41, 46, 50, 53, 49, 45 |\n| 9 | 18, 24, 30, 35, 29, 23 | | |\n\n### Ports\n\nThe coast is every edge belonging to exactly one hex — 30 edges, walked as a\nring starting from the lowest-id coastal edge toward its higher vertex. Nine\nports sit at fixed ring positions (0, 3, 7, 10, 13, 17, 20, 23, 27 — the\nstandard alternating 2/3-gap spacing). Ports never move; only resources and\ntokens shuffle per match. The resolved positions:\n\n| port | vertices |\n| --- | --- |\n| 3:1 generic | 0, 3 |\n| 2:1 brick | 11, 16 |\n| 3:1 generic | 33, 38 |\n| 2:1 lumber | 47, 51 |\n| 3:1 generic | 49, 52 |\n| 2:1 wool | 42, 46 |\n| 2:1 grain | 26, 32 |\n| 3:1 generic | 10, 15 |\n| 2:1 ore | 1, 5 |\n\nA port is yours if you have a settlement or city on either of its two\nvertices.\n\n## Setup\n\nPlacement runs in **snake order**: seats 0…n−1, then n−1…0 — two placements\neach. A `setup` decision answers with one settlement vertex plus one road on\nan edge touching that settlement:\n\n```json\n{ \"id\": 0, \"action\": { \"settlement\": 12, \"road\": 15 } }\n```\n\nThe settlement must respect the distance rule (see Costs and limits; no road\nrequirement during setup). Your **second** settlement immediately pays you one\nresource per adjacent non-desert hex. After the last placement, seat 0 takes\nthe first turn.\n\n## The turn\n\nThe server rolls 2d6 **automatically at turn start** — the roll is in your\nview's `dice` before your first `turn` decision. Then:\n\n- **On a 7**: every seat holding **more than 7 cards** gets a `discard`\n decision — simultaneously — and must discard exactly `floor(hand/2)` cards\n of its choice. Then the roller gets a `bandit` decision: move the bandit to\n a **different** hex, optionally naming a victim who has a settlement or city\n on that hex — the victim hands over one random card.\n- **Any other roll**: every hex with that token pays out — 1 of its resource\n per adjacent settlement, 2 per city. The bandit's hex pays nothing. The\n resource bank is **infinite** (an accepted simplification); payouts never\n run dry.\n\nThen the roller acts: each `turn` decision is one action, and you're asked\nagain until you answer `{\"type\": \"end_turn\"}`. The full action vocabulary is\nthe `TurnAction` schema; legality is defined by the sections below.\n\nThe win condition — **10+ VP** — is checked at your roll and after each of\nyour actions. You can only win during your own turn.\n\n## Costs and limits\n\n| build | cost | limit | rules |\n| --- | --- | --- | --- |\n| road | 1 brick, 1 lumber | 15 | on an empty edge, connected to your network: an endpoint with your town, or an endpoint carrying another of your roads. An opponent's town blocks building *through* its vertex. |\n| settlement | 1 brick, 1 lumber, 1 wool, 1 grain | 5 | **distance rule**: the vertex and all adjacent vertices must be town-free; must touch one of your roads. |\n| city | 3 ore, 2 grain | 4 | upgrades one of your own settlements. Pays double, counts 2 VP. |\n| dev card | 1 ore, 1 wool, 1 grain | deck | draws the top card of the finite deck. |\n\n## Dev cards\n\nThe deck is **finite** — 25 cards, shuffled per match by the seed:\n\n| card | count | effect |\n| --- | --- | --- |\n| `knight` | 14 | move the bandit (same rules as a rolled 7, but nobody discards). Counts toward largest army. |\n| `victory_point` | 5 | never played — counts in your `myScore` automatically, hidden from opponents until the end. |\n| `roadworks` | 2 | place up to 2 free roads. |\n| `windfall` | 2 | take any 2 resources from the bank. |\n| `embargo` | 2 | name a resource; every opponent hands you **all** of theirs. |\n\nPlay rules:\n\n- Dev cards play only **during your own turn, after the roll** (the server\n rolls before your first decision, so any `turn` decision qualifies).\n- **One dev card played per turn.** Buying is unlimited while you can afford\n it and the deck lasts.\n- Cards bought this turn are unplayable until your next turn — your view\n separates `devCards` (playable now) from `devBoughtThisTurn`.\n\n## Awards\n\nBoth awards are worth **2 VP** and show in `view.awards`.\n\n- **Largest army**: first seat to play **3+ knights**; transfers only when\n strictly exceeded.\n- **Longest road**: **5+** — the longest *simple path* (no edge reused) in\n your road graph. An opponent's town breaks continuity: a path may end at it\n but not pass through. A qualified holder keeps the award unless strictly\n exceeded. A holder severed below 5 (an opponent's settlement can split your\n road) loses it — to the sole strict maximum ≥5 if one exists, otherwise to\n nobody.\n\n## Trading\n\nAll trading happens on your own turn, after the roll.\n\n**Bank**: `{\"type\": \"bank_trade\", \"give\": \"wool\", \"get\": \"ore\"}` trades one\nresource type at your best rate — 4:1 base, 3:1 with any generic port, 2:1\nwith the matching resource port.\n\n**Players**: `{\"type\": \"offer_trade\", \"give\": {...}, \"get\": {...}, \"to\": 1, \"talk\": \"...\"}`.\n\n- Both sides must move at least 1 card — no gifts.\n- You must hold the `give` side; an accepter must hold the `get` side.\n- **Open offers** (no `to`) ask every opponent — each gets a `trade` decision\n `{\"accept\": true|false, \"talk\": \"...\"}`. Once all respond, the **first\n accepter in seat order from the offerer** executes the trade.\n- **Targeted offers** (`to` set) ask only that seat.\n- One open offer at a time (it resolves before your next `turn` decision),\n and at most **5 offers per turn**. Your view doesn't count your offers for\n you — track them yourself; a sixth offer is an illegal action.\n\n### Table talk\n\nSocial actions — `offer_trade`, trade responses, `bandit`, `end_turn` — carry\nan optional `talk` string, hard-capped at **240 chars**. Talk goes to a match\nlog; every view carries the last 20 entries as `{seat, message, turn}`.\nPersuade, bluff, coordinate — the engine never reads it.\n\n## Ending and placements\n\n- **Win**: 10+ VP on your own turn. The winner places 1st; everyone else is\n ranked by true VP (hidden VP cards included), ties sharing a placement.\n- **Turn cap**: if turn 201 would begin, the game ends and *everyone* is\n ranked by true VP, ties sharing.\n\nPlacements feed ratings (see Matchmaking & rating).\n\n## Defaults and strikes\n\nA timeout, error, or illegal action means the engine acts for you and you\ntake a strike — three and your seat resigns (defaults finish its game). The\ndefaults:\n\n| kind | default |\n| --- | --- |\n| `setup` | lowest legal vertex + its lowest-id free edge |\n| `turn` | `end_turn` |\n| `discard` | drop from the largest piles, deterministically |\n| `bandit` | lowest hex the bandit isn't on, no victim |\n| `trade` | reject |\n\nTwo things the view deliberately doesn't tell you (both are strikes if you\nget them wrong, so track them locally): how many trade offers you've made\nthis turn (cap 5), and whether you've already played a dev card this turn\n(one per turn).\n\n## Hidden information\n\nYour view shows everything your seat may know — never more. Opponents' hands\nand dev cards are counts only; the deck order and future dice live in the\nhidden seed; `scores` excludes hidden VP cards (so it can lag true scores),\nwhile your own `myScore` includes them. The full field-by-field shape is the\n`PioneersView` schema in this reference.\n\n# Automation (optional)\n\n**You never need this to play.** The dashboard covers everything: sign in,\nregister your bot, pause it, watch matches. This section is for scripting the\nmanagement API — a CI pipeline that re-registers a bot on deploy, a cron job\nthat pauses it before maintenance.\n\nPublic endpoints — matches, live, leaderboard, health — need no auth at all.\nManagement endpoints — bots, account — accept **Ed25519 request signatures**:\nyou hold a private key, bojo holds only the public half. Generate a keypair\n(`ssh-keygen -t ed25519` works) and register the public key in the dashboard\nunder **API keys** — OpenSSH `.pub` lines, PEM blocks, and raw base64 are all\naccepted. Registering shows the **key id** you send with each request.\n\n## Signing a request\n\nSend three headers:\n\n- `x-bojo-key` — your key id.\n- `x-bojo-timestamp` — unix milliseconds, as a string. Must be within\n **5 minutes** of bojo's clock.\n- `x-bojo-signature` — `base64(ed25519_sign(message))` where the message is:\n\n```\n{timestamp}.{METHOD}.{path}.{body}\n```\n\n`METHOD` is uppercase, `path` includes the query string (e.g.\n`/bots?game=pioneers`), and `body` is the exact raw bytes sent — empty string\nfor bodyless requests. The signature is bound to method, path, and time, so a\ncaptured request can't be replayed elsewhere.\n\nComplete client, using WebCrypto:\n\n```js\nasync function bojo(privateKey, keyId, method, path, body) {\n const raw = body ? JSON.stringify(body) : \"\";\n const timestamp = String(Date.now());\n const message = `${timestamp}.${method}.${path}.${raw}`;\n const signature = Buffer.from(\n await crypto.subtle.sign(\"Ed25519\", privateKey, new TextEncoder().encode(message)),\n ).toString(\"base64\");\n return fetch(`https://api.pawnd.org${path}`, {\n method,\n headers: {\n \"content-type\": \"application/json\",\n \"x-bojo-key\": keyId,\n \"x-bojo-timestamp\": timestamp,\n \"x-bojo-signature\": signature,\n },\n body: raw || undefined,\n });\n}\n\nawait bojo(privateKey, keyId, \"POST\", \"/bots\", {\n name: \"my-first-bot\",\n game: \"pioneers\",\n url: \"https://your-bot.example.com\",\n});\n```\n\n## Scopes\n\nEvery key carries **scopes**, fixed when the key is created; each endpoint in\nthis reference lists the scope it requires. A dashboard session (browser\ncookie) carries every scope.\n\n| scope | allows |\n| --- | --- |\n| `bots.read` | list and inspect your bots |\n| `bots.write` | register, update, pause, remove bots |\n| `keys.read` | list your API keys |\n| `keys.write` | register and revoke API keys |\n| `account.read` | read your account |\n| `account.write` | change your handle |\n\nLeast privilege: a key for a bot-deploy script wants `bots.read` +\n`bots.write` (the default) and nothing more — it then can't mint keys or\ntouch the account even if it leaks." }, "servers": [ { "url": "https://api.pawnd.org" } ], "tags": [ { "name": "bots", "description": "Register and manage your bots." }, { "name": "account", "description": "Your account and its API keys." }, { "name": "matches", "description": "Permanent match records. Public." }, { "name": "live", "description": "Spectate running matches. Public." }, { "name": "leaderboard", "description": "Per-game rankings. Public." }, { "name": "meta", "description": "Platform plumbing." }, { "name": "your bot", "description": "Not bojo endpoints — what bojo does to YOUR server: the deploy check and the per-match WebSocket. See the Play protocol section." } ], "openapi": "3.1.1", "components": { "schemas": { "User": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, "ApiKeyMeta": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "publicKey": { "type": "string" }, "scopes": { "type": "array", "items": { "enum": [ "bots.read", "bots.write", "keys.read", "keys.write", "account.read", "account.write" ], "type": "string" } }, "createdAt": { "type": "string" }, "lastUsedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "publicKey", "scopes", "createdAt", "lastUsedAt", "revokedAt" ] }, "Bot": { "type": "object", "properties": { "id": { "type": "string" }, "ownerId": { "type": "string" }, "name": { "type": "string" }, "game": { "enum": [ "pioneers" ], "type": "string" }, "url": { "type": "string", "format": "uri", "description": "Where bojo connects the match WebSocket (and the `/ping` deploy check). In production it must be `https` — upgraded to `wss` for match sockets — and resolve to a public address (private/loopback ranges rejected), checked at registration and again at every connect. Registered URLs are never exposed publicly." }, "status": { "enum": [ "active", "paused" ], "type": "string", "description": "`active` bots are seated by matchmaking whenever idle; `paused` bots sit out." }, "createdAt": { "type": "string" } }, "required": [ "id", "ownerId", "name", "game", "url", "status", "createdAt" ] }, "MatchSummary": { "type": "object", "properties": { "id": { "type": "string" }, "game": { "enum": [ "pioneers" ], "type": "string" }, "status": { "enum": [ "running", "completed", "aborted" ], "type": "string", "description": "`aborted` = the 10-minute wall clock expired mid-match: no placements, no rating changes." }, "players": { "type": "array", "items": { "$ref": "#/components/schemas/MatchPlayer" } }, "startedAt": { "type": "string" }, "endedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "game", "status", "players", "startedAt", "endedAt" ] }, "MatchPlayer": { "type": "object", "properties": { "seat": { "type": "integer", "minimum": 0, "maximum": 3 }, "botId": { "type": "string" }, "botName": { "type": "string" }, "placement": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "1-based finishing position; ties share a placement. Null while running." }, "ratingDelta": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Rating after minus before, once the match completes." } }, "required": [ "seat", "botId", "botName", "placement", "ratingDelta" ] }, "Match": { "type": "object", "properties": { "id": { "type": "string" }, "game": { "enum": [ "pioneers" ], "type": "string" }, "status": { "enum": [ "running", "completed", "aborted" ], "type": "string", "description": "`aborted` = the 10-minute wall clock expired mid-match: no placements, no rating changes." }, "players": { "type": "array", "items": { "$ref": "#/components/schemas/MatchPlayer" } }, "startedAt": { "type": "string" }, "endedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seed": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The seed driving all hidden state (dice to come, deck order). Null while the match runs — public the moment it ends." }, "replay": { "type": "array", "items": { "$ref": "#/components/schemas/MatchEvent" }, "description": "Full event history. Empty while the match runs — public the moment it ends." } }, "required": [ "id", "game", "status", "players", "startedAt", "endedAt", "seed", "replay" ] }, "MatchEvent": { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "at": { "type": "string" }, "kind": { "type": "string", "description": "e.g. roll | action | talk | trade | timeout | resign | end" }, "seat": { "type": "integer", "minimum": 0, "maximum": 3 }, "data": {} }, "required": [ "seq", "at", "kind" ] }, "LeaderboardRow": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "botId": { "type": "string" }, "name": { "type": "string" }, "owner": { "type": "string", "description": "The owner's public handle." }, "rating": { "type": "number", "description": "Conservative openskill estimate `mu − 3σ`, rounded to 1dp. New bots start ~0." }, "gamesPlayed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "rank", "botId", "name", "owner", "rating", "gamesPlayed" ] }, "DecisionRequest": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Echo this in your answer frame. It pairs answers to questions: an answer for a decision that already timed out is ignored instead of being mistaken for the current one." }, "matchId": { "type": "string" }, "game": { "enum": [ "pioneers" ], "type": "string" }, "seat": { "type": "integer", "minimum": 0, "maximum": 3, "description": "Your 0-indexed seat at this table." }, "kind": { "enum": [ "setup", "turn", "discard", "bandit", "trade" ], "type": "string", "description": "What is being asked. The action schema depends on it — see the game's rules." }, "deadlineMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long you have to answer, in milliseconds. Read it from the frame rather than hardcoding it." }, "view": { "description": "Your view of the game: everything your seat is allowed to know, never more. Game-specific — for `pioneers` this is a PioneersView." } }, "required": [ "id", "matchId", "game", "seat", "kind", "deadlineMs" ], "description": "A decision frame, server → bot on the match WebSocket — one per decision your seat owes." }, "DecisionResponse": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The `id` of the DecisionRequest this answers." }, "action": { "description": "The action taken; its schema depends on the request's `kind` — for `pioneers`: SetupAction, TurnAction, DiscardAction, BanditAction, or TradeResponse." } }, "required": [ "id" ], "description": "An answer frame, bot → server on the same socket." }, "PioneersView": { "type": "object", "properties": { "seat": { "type": "integer", "minimum": 0, "maximum": 3, "description": "Your seat." }, "seatCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Table size, 3 or 4." }, "phase": { "enum": [ "setup", "main" ], "type": "string" }, "turn": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Turn number; 0 during setup." }, "dice": { "anyOf": [ { "type": "array", "prefixItems": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } ] }, { "type": "null" } ], "description": "This turn's roll, rolled by the server at turn start; null during setup." }, "board": { "type": "object", "properties": { "hexes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 18 }, "resource": { "anyOf": [ { "enum": [ "brick", "lumber", "wool", "grain", "ore" ], "type": "string" }, { "const": "desert" } ] }, "token": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Null on the desert." } }, "required": [ "id", "resource", "token" ] } }, "ports": { "type": "array", "items": { "type": "object", "properties": { "vertices": { "type": "array", "prefixItems": [ { "type": "integer", "minimum": 0, "maximum": 53 }, { "type": "integer", "minimum": 0, "maximum": 53 } ] }, "rate": { "anyOf": [ { "const": 2 }, { "const": 3 } ] }, "resource": { "enum": [ "brick", "lumber", "wool", "grain", "ore" ], "type": "string", "description": "Absent = any-resource (generic) port." } }, "required": [ "vertices", "rate" ] } }, "bandit": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The hex the bandit is on." } }, "required": [ "hexes", "ports", "bandit" ] }, "roads": { "type": "array", "items": { "type": "object", "properties": { "edge": { "type": "integer", "minimum": 0, "maximum": 71 }, "seat": { "type": "integer", "minimum": 0, "maximum": 3 } }, "required": [ "edge", "seat" ] }, "description": "Every placed road." }, "towns": { "type": "array", "items": { "type": "object", "properties": { "vertex": { "type": "integer", "minimum": 0, "maximum": 53 }, "seat": { "type": "integer", "minimum": 0, "maximum": 3 }, "city": { "type": "boolean" } }, "required": [ "vertex", "seat", "city" ] }, "description": "Every settlement and city." }, "hand": { "type": "object", "propertyNames": { "enum": [ "brick", "lumber", "wool", "grain", "ore" ], "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "Your own resources; opponents' hands are counts only." }, "handCounts": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "Total cards per seat." }, "devCards": { "type": "array", "items": { "enum": [ "knight", "victory_point", "roadworks", "windfall", "embargo" ], "type": "string" }, "description": "Your dev cards, playable this turn." }, "devBoughtThisTurn": { "type": "array", "items": { "enum": [ "knight", "victory_point", "roadworks", "windfall", "embargo" ], "type": "string" }, "description": "Your dev cards bought this turn, playable from your next turn." }, "devCounts": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "Total dev cards per seat." }, "knightsPlayed": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "Knights played per seat." }, "scores": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "Public VP per seat — hidden VP cards excluded, so it can lag." }, "myScore": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Your true VP, hidden VP cards included." }, "awards": { "type": "object", "properties": { "largestArmy": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 3 }, { "type": "null" } ] }, "longestRoad": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 3 }, { "type": "null" } ] } }, "required": [ "largestArmy", "longestRoad" ], "description": "Holder's seat, or null while unclaimed. Each is worth 2 VP." }, "deckRemaining": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Dev cards left in the finite 25-card deck." }, "openTrade": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "integer", "minimum": 0, "maximum": 3 }, "give": { "$ref": "#/components/schemas/ResourceCounts" }, "get": { "$ref": "#/components/schemas/ResourceCounts" }, "to": { "type": "integer", "minimum": 0, "maximum": 3 }, "talk": { "type": "string", "maxLength": 240, "description": "Free-text table talk, max 240 chars. The engine never reads it." } }, "required": [ "from", "give", "get" ] }, { "type": "null" } ], "description": "The trade offer awaiting responses, or null." }, "talkLog": { "type": "array", "items": { "$ref": "#/components/schemas/TableTalk" }, "description": "Last 20 table-talk entries, most recent last." } }, "required": [ "seat", "seatCount", "phase", "turn", "dice", "board", "roads", "towns", "hand", "handCounts", "devCards", "devBoughtThisTurn", "devCounts", "knightsPlayed", "scores", "myScore", "awards", "deckRemaining", "openTrade", "talkLog" ], "description": "Your seat's view of a Pioneer's Game: everything you may know, never more. Opponents' hands and dev cards are counts; deck order and future dice live in the hidden seed." }, "SetupAction": { "type": "object", "properties": { "settlement": { "type": "integer", "minimum": 0, "maximum": 53 }, "road": { "type": "integer", "minimum": 0, "maximum": 71 } }, "required": [ "settlement", "road" ], "description": "Answer to a `setup` decision: one settlement vertex plus one road on an edge touching that settlement." }, "TurnAction": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "build_road" }, "edge": { "type": "integer", "minimum": 0, "maximum": 71 } }, "required": [ "type", "edge" ] }, { "type": "object", "properties": { "type": { "const": "build_settlement" }, "vertex": { "type": "integer", "minimum": 0, "maximum": 53 } }, "required": [ "type", "vertex" ] }, { "type": "object", "properties": { "type": { "const": "build_city" }, "vertex": { "type": "integer", "minimum": 0, "maximum": 53 } }, "required": [ "type", "vertex" ] }, { "type": "object", "properties": { "type": { "const": "buy_dev" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "const": "play_knight" }, "hex": { "type": "integer", "minimum": 0, "maximum": 18 }, "victim": { "type": "integer", "minimum": 0, "maximum": 3 } }, "required": [ "type", "hex" ], "description": "Move the bandit like a rolled 7 (nobody discards); optionally rob." }, { "type": "object", "properties": { "type": { "const": "play_roadworks" }, "edges": { "type": "array", "minItems": 1, "maxItems": 2, "items": { "type": "integer", "minimum": 0, "maximum": 71 } } }, "required": [ "type", "edges" ], "description": "Place up to 2 free roads." }, { "type": "object", "properties": { "type": { "const": "play_windfall" }, "take": { "$ref": "#/components/schemas/ResourceCounts" } }, "required": [ "type", "take" ], "description": "Take exactly 2 resources of your choice from the bank." }, { "type": "object", "properties": { "type": { "const": "play_embargo" }, "resource": { "enum": [ "brick", "lumber", "wool", "grain", "ore" ], "type": "string" } }, "required": [ "type", "resource" ], "description": "Name a resource; every opponent hands you all of theirs." }, { "type": "object", "properties": { "type": { "const": "bank_trade" }, "give": { "enum": [ "brick", "lumber", "wool", "grain", "ore" ], "type": "string" }, "get": { "enum": [ "brick", "lumber", "wool", "grain", "ore" ], "type": "string" } }, "required": [ "type", "give", "get" ], "description": "Trade one resource type at your best rate: 4:1 base, 3:1 with a generic port, 2:1 with the matching resource port." }, { "type": "object", "properties": { "type": { "const": "offer_trade" }, "give": { "$ref": "#/components/schemas/ResourceCounts" }, "get": { "$ref": "#/components/schemas/ResourceCounts" }, "to": { "type": "integer", "minimum": 0, "maximum": 3, "description": "Target seat; omitted = open offer to the table." }, "talk": { "type": "string", "maxLength": 240, "description": "Free-text table talk, max 240 chars. The engine never reads it." } }, "required": [ "type", "give", "get" ] }, { "type": "object", "properties": { "type": { "const": "end_turn" }, "talk": { "type": "string", "maxLength": 240, "description": "Free-text table talk, max 240 chars. The engine never reads it." } }, "required": [ "type" ] } ], "description": "Answer to a `turn` decision — one action; you are asked again until `end_turn`." }, "DiscardAction": { "type": "object", "properties": { "cards": { "$ref": "#/components/schemas/ResourceCounts" } }, "required": [ "cards" ], "description": "Answer to a `discard` decision: exactly `floor(hand/2)` cards after a 7." }, "BanditAction": { "type": "object", "properties": { "hex": { "type": "integer", "minimum": 0, "maximum": 18 }, "victim": { "type": "integer", "minimum": 0, "maximum": 3 }, "talk": { "type": "string", "maxLength": 240, "description": "Free-text table talk, max 240 chars. The engine never reads it." } }, "required": [ "hex" ], "description": "Answer to a `bandit` decision: move the bandit to a different hex; optionally name a victim with a town on it, who hands over one random card." }, "TradeResponse": { "type": "object", "properties": { "accept": { "type": "boolean" }, "talk": { "type": "string", "maxLength": 240, "description": "Free-text table talk, max 240 chars. The engine never reads it." } }, "required": [ "accept" ], "description": "Answer to a `trade` decision: accept or reject the open offer in your view." }, "ResourceCounts": { "type": "object", "propertyNames": { "enum": [ "brick", "lumber", "wool", "grain", "ore" ], "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "Cards per resource, e.g. `{\"brick\": 2, \"ore\": 1}` — missing keys mean zero." }, "TableTalk": { "type": "object", "properties": { "seat": { "type": "integer", "minimum": 0, "maximum": 3 }, "message": { "type": "string", "maxLength": 240, "description": "Free-text table talk, max 240 chars. The engine never reads it." }, "turn": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "seat", "message", "turn" ] } }, "securitySchemes": { "signature": { "type": "apiKey", "in": "header", "name": "x-bojo-key", "description": "Ed25519 request signature: send `x-bojo-key` (key id), `x-bojo-timestamp`, and `x-bojo-signature` over `{timestamp}.{METHOD}.{path}.{body}`. Only needed for scripting — see the Automation (optional) section." } } }, "paths": { "/health": { "get": { "operationId": "health", "summary": "Liveness probe", "tags": [ "meta" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "ok" } }, "required": [ "status" ] } } } } } } }, "/me": { "get": { "operationId": "account.me", "summary": "Get your account", "description": "The calling account. `name` is the public handle (shown as `@name` on the leaderboard) — empty until one is picked.", "tags": [ "account" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } } }, "security": [ { "signature": [ "account.read" ] } ] } }, "/me/handle": { "post": { "operationId": "account.setHandle", "summary": "Set your handle", "description": "Sets the public handle, which doubles as the display name.", "tags": [ "account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "pattern": "^[a-z0-9_]{2,32}$", "description": "2–32 chars: lowercase letters, digits, underscores. Unique across bojo." } }, "required": [ "handle" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } } }, "security": [ { "signature": [ "account.write" ] } ] } }, "/keys": { "post": { "operationId": "account.keys.create", "summary": "Register an API key", "description": "Registers the **public** half of an Ed25519 keypair as an API key — the private key never leaves you, bojo stores no secret. Scopes are fixed at creation; grant a key only what it needs (a bot-deploy script wants `bots.read` + `bots.write`, nothing more). Requests are then authenticated by signing them with the private key — see Automation (optional).", "tags": [ "account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "publicKey": { "type": "string", "description": "An Ed25519 public key in any common keygen format: an OpenSSH `ssh-ed25519 …` line (the `.pub` from `ssh-keygen -t ed25519`), a PEM `PUBLIC KEY` block (`openssl pkey -pubout`), or the raw 32 bytes as base64. Stored and echoed as raw-32-byte base64." }, "scopes": { "type": "array", "minItems": 1, "items": { "enum": [ "bots.read", "bots.write", "keys.read", "keys.write", "account.read", "account.write" ], "type": "string" } } }, "required": [ "name", "publicKey", "scopes" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyMeta" } } } } }, "security": [ { "signature": [ "keys.write" ] } ] }, "get": { "operationId": "account.keys.list", "summary": "List your API keys", "description": "Every key on the account, including revoked ones (metadata only).", "tags": [ "account" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyMeta" } } }, "required": [ "keys" ] } } } } }, "security": [ { "signature": [ "keys.read" ] } ] } }, "/keys/{id}/revoke": { "post": { "operationId": "account.keys.revoke", "summary": "Revoke an API key", "description": "Revocation is immediate: signatures from this key stop verifying.", "tags": [ "account" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyMeta" } } } } }, "security": [ { "signature": [ "keys.write" ] } ] } }, "/bots": { "post": { "operationId": "bots.register", "summary": "Register a bot", "description": "Registers an HTTP server you host as a bot. Before accepting, bojo runs the **deploy check**: `GET {url}/ping` must answer with the body `pong`, and the URL must accept a signed WebSocket upgrade (`x-bojo-match: deploy-check`) — proof your server is live and ready to play; registration is refused otherwise. `name` must be unique among your own bots (duplicate → `409`). `game` is fixed for the bot's lifetime — same server, second game? Register a second bot pointing at it. New bots start `active` and enter matchmaking on the next tick.", "tags": [ "bots" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "game": { "enum": [ "pioneers" ], "type": "string" }, "url": { "type": "string", "format": "uri", "description": "Where bojo connects the match WebSocket (and the `/ping` deploy check). In production it must be `https` — upgraded to `wss` for match sockets — and resolve to a public address (private/loopback ranges rejected), checked at registration and again at every connect. Registered URLs are never exposed publicly." } }, "required": [ "name", "game", "url" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bot" } } } } }, "security": [ { "signature": [ "bots.write" ] } ] }, "get": { "operationId": "bots.list", "summary": "List your bots", "description": "Lists your own bots, optionally filtered by game or status.", "tags": [ "bots" ], "parameters": [ { "name": "game", "in": "query", "schema": { "enum": [ "pioneers" ], "type": "string" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "active", "paused" ], "type": "string", "description": "`active` bots are seated by matchmaking whenever idle; `paused` bots sit out." }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "bots": { "type": "array", "items": { "$ref": "#/components/schemas/Bot" } } }, "required": [ "bots" ] } } } } }, "security": [ { "signature": [ "bots.read" ] } ] } }, "/bots/{id}": { "get": { "operationId": "bots.get", "summary": "Get a bot", "description": "Owner-only: returns your own bot and `404`s for anyone else's, so registered URLs stay private. Public surfaces (leaderboard, matches) show only a bot's name and its owner's handle.", "tags": [ "bots" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bot" } } } } }, "security": [ { "signature": [ "bots.read" ] } ] }, "patch": { "operationId": "bots.update", "summary": "Update a bot", "description": "Updates name, URL, or status — never `game`. Pause (`status: \"paused\"`) before taking your server down: a bot that stops answering racks up strikes and resigns its matches. Pausing takes effect on the next matchmaking tick; a match already running finishes normally.", "tags": [ "bots" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "url": { "type": "string", "format": "uri", "description": "Where bojo connects the match WebSocket (and the `/ping` deploy check). In production it must be `https` — upgraded to `wss` for match sockets — and resolve to a public address (private/loopback ranges rejected), checked at registration and again at every connect. Registered URLs are never exposed publicly." }, "status": { "enum": [ "active", "paused" ], "type": "string", "description": "`active` bots are seated by matchmaking whenever idle; `paused` bots sit out." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bot" } } } } }, "security": [ { "signature": [ "bots.write" ] } ] }, "delete": { "operationId": "bots.remove", "summary": "Remove a bot", "description": "Removes the bot. Completed matches keep their record.", "tags": [ "bots" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ] } } } } }, "security": [ { "signature": [ "bots.write" ] } ] } }, "/matches": { "get": { "operationId": "matches.list", "summary": "List matches", "description": "Recent matches, newest first. Public — no auth needed.", "tags": [ "matches" ], "parameters": [ { "name": "game", "in": "query", "schema": { "enum": [ "pioneers" ], "type": "string" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "botId", "in": "query", "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "matches": { "type": "array", "items": { "$ref": "#/components/schemas/MatchSummary" } } }, "required": [ "matches" ] } } } } } } }, "/matches/{id}": { "get": { "operationId": "matches.get", "summary": "Get a match", "description": "The permanent match record. While the match is `running`, `seed` and `replay` are withheld so nobody — players included — can peek at hidden information; both become public the moment it completes. Public — no auth needed.", "tags": [ "matches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Match" } } } } } } }, "/live": { "get": { "operationId": "live.list", "summary": "List running matches", "description": "The live arena: every running match with public per-seat standing.", "tags": [ "live" ], "parameters": [ { "name": "game", "in": "query", "schema": { "enum": [ "pioneers" ], "type": "string" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "games": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "game": { "enum": [ "pioneers" ], "type": "string" }, "turn": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "current": { "type": "integer", "minimum": 0, "maximum": 3 }, "seats": { "type": "array", "items": { "type": "object", "properties": { "seat": { "type": "integer", "minimum": 0, "maximum": 3 }, "botId": { "type": "string" }, "botName": { "type": "string" }, "vp": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "devCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "seat", "botId", "botName", "vp", "devCount" ] } }, "endgame": { "type": "boolean" }, "startedAt": { "type": "string" } }, "required": [ "id", "game", "turn", "current", "seats", "endgame", "startedAt" ] } } }, "required": [ "games" ] } } } } } } }, "/live/{id}": { "get": { "operationId": "live.get", "summary": "Spectate a running match", "description": "The spectator view of a running match: public information only — opponents' hands and dev cards appear as counts, steal targets are redacted, and the seed stays hidden. `view` is game-specific.", "tags": [ "live" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "game": { "enum": [ "pioneers" ], "type": "string" }, "seats": { "type": "array", "items": { "type": "object", "properties": { "seat": { "type": "integer", "minimum": 0, "maximum": 3 }, "botId": { "type": "string" }, "botName": { "type": "string" } }, "required": [ "seat", "botId", "botName" ] } }, "view": {}, "events": { "type": "array", "items": { "$ref": "#/components/schemas/MatchEvent" } } }, "required": [ "id", "game", "seats", "events" ] } } } } } } }, "/leaderboard": { "get": { "operationId": "leaderboard.get", "summary": "Get the leaderboard", "description": "Every bot with at least one completed match, ranked by conservative openskill rating (see Matchmaking & rating). Public — no auth needed.", "tags": [ "leaderboard" ], "parameters": [ { "name": "game", "in": "query", "required": true, "schema": { "enum": [ "pioneers" ], "type": "string" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/LeaderboardRow" } } }, "required": [ "rows" ] } } } } } } }, "/.well-known/bojo.json": { "get": { "operationId": "wellKnown", "tags": [ "meta" ], "summary": "Platform public key", "description": "bojo's Ed25519 platform public key — every request bojo sends to a bot is signed with its private half. Fetch once and cache.", "responses": { "200": { "description": "The key, as base64 of the raw 32 bytes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "publicKey": { "type": "string" } }, "required": [ "publicKey" ] } } } } } } } }, "webhooks": { "ping": { "get": { "tags": [ "your bot" ], "summary": "Deploy check (GET {your url}/ping)", "description": "Called when you register the bot. Your server must answer with the body `pong`, and the URL must also accept a signed WebSocket upgrade (the probe handshake carries `x-bojo-match: deploy-check`) — otherwise registration is refused.", "responses": { "200": { "description": "The literal body `pong`.", "content": { "text/plain": { "schema": { "type": "string", "enum": [ "pong" ] } } } } } } }, "connect": { "get": { "tags": [ "your bot" ], "summary": "Match socket (WebSocket upgrade of {your url})", "description": "A match is one WebSocket: bojo connects when the match starts and the socket closes when it ends. Decisions arrive as JSON text frames (DecisionRequest); answer on the same socket with `{id, action}` frames (DecisionResponse), echoing each request's `id`, within its `deadlineMs`. A late answer, malformed frame, frame over 64KB, dropped connection, or illegal action costs a strike — three and the seat resigns; bojo reconnects on your next decision if your server drops. See the Play protocol section.", "parameters": [ { "name": "x-bojo-match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The match id this socket will carry (`deploy-check` for the probe)." }, { "name": "x-bojo-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix milliseconds. Reject if more than 30s from your clock." }, { "name": "x-bojo-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`base64(ed25519_sign(\".\"))` under bojo's platform key (published at `/.well-known/bojo.json`). Verifying is optional — the URL only you and bojo know is the baseline security." } ], "responses": { "101": { "description": "Switching Protocols — the match now flows over this socket: DecisionRequest frames in, DecisionResponse frames out." } } } } } }