Publieke / bot-API

Stuur Authorization: Bearer kirichess_pat_… bij elk verzoek. Er zijn precies twee scopes. Een token draagt nooit admin- of 2FA-claims, ook niet als het account dat wel doet. Er kunnen tot 10 tokens tegelijk actief zijn. Een token geldt 90 dagen, tenzij je een andere levensduur kiest tussen 1 en 365 dagen, en je kunt het eerder intrekken via de kaart API-tokens op je profielpagina.

Na kirichess_pat_ volgen 43 tekens uit het URL-veilige base64-alfabet (A–Z, a–z, 0–9, koppelteken, onderstrepingsteken) en daarna 6 controlesomtekens. De controlesom is de CRC-32 (IEEE) van die 43 tekens, geschreven als 6 base62-cijfers in het alfabet 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz, links aangevuld met nullen. Een secret scanner kan een tekenreeks die die controle niet haalt afwijzen zonder deze server te bevragen.

• read, identiteit, je partijen, afgelopen herhalingen, je openstaande uitdagingen, ratings in de botpool, botoproepen.
• play, ongewaardeerde partijen en uitdagingen aanmaken, zetten en opgeven, en aansluiten bij de botmatchmaking via de hub. Play impliceert read op het moment van uitgifte.

Je engine draait in het proces dat deze API aanroept. Browserorigins anders dan deze site blijven geblokkeerd; CORS wordt voor deze API niet verruimd.

curl https://api.kirichess.com/api/v1/account \
  -H "Authorization: Bearer $KIRICHESS_API_TOKEN"

POST /api/v1/games maakt alleen een solo- of zelfspeelpartij aan, beide stoelen ben jij, om de engine van begin tot eind te oefenen. Een opponentId die naar iemand anders wijst wordt geweigerd: gekoppelde partijen lopen altijd via POST /api/v1/challenges of de botpool. Gewaardeerd meten is een bewuste keuze: verbind met de partij-hub met hetzelfde token en roep JoinQueue aan met een officiële preset (bounty1, burn1, steal1, steal2, burn2, steal3). Dat wordt omgezet naar bot:{preset} en mengt nooit met de Glicko van mensen.

De bot-pool is een gebaar van hoffelijkheid naar eerlijke bot-auteurs, geen technische grens: een script dat inlogt met het wachtwoord van een account is bij de wachtrij niet te onderscheiden van een browser en komt in de menselijke pool terecht. Spelen in de menselijke pool vanuit een script is tegen de regels, ongeacht welke inloggegevens daarvoor worden gebruikt.

curl -X POST https://api.kirichess.com/api/v1/games \
  -H "Authorization: Bearer $KIRICHESS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"preset":"bounty1","opponentId":null,"rated":false}'

Verbind met wss://api.kirichess.com/hubs/game. Een bot authenticeert op dezelfde manier als overal elders in deze API: stuur Authorization: Bearer kirichess_pat_… bij het verbindingsverzoek. De eigen site zet een kortlevend sessie-JWT in de access_token-query, omdat een browser geen header kan meegeven bij een WebSocket-handshake. De server aanvaardt een kirichess_pat_…-token in die query nog steeds. Zet er zelf geen in: die wordt vastgelegd in het proxylog van Fly, in het requestlog van Cloudflare en in de request-URL die Sentry vastlegt.

Spelersmethodes: JoinQueue, SubmitMove, Resign, OfferDraw, RespondDraw en LeaveQueue. Events: MatchFound, MovePlayed, GameEnded, DrawOffered, DrawDeclined, OpponentDisconnected en OpponentReconnected. WatchChallenge en UnwatchChallenge abonneren deze verbinding op een uitdaging die jij hebt aangemaakt; OfferRematch en AcceptRematch gaan verder met een afgelopen partij. JoinAsSpectator blijft anoniem. Een werkende lus is verbinden, JoinQueue, wachten op MatchFound, dan JoinGame(gameId) om de huidige stelling te krijgen en je te abonneren op de events van die partij voordat je SubmitMove aanroept of op MovePlayed reageert; sla je JoinGame over, dan komt er nooit een MovePlayed-event aan. Zetten in een via de hub gekoppelde partij kunnen ook via POST /api/v1/games/{id}/moves in plaats van de hub, als dat makkelijker is voor je client.