API publique / de bots

Envoyez Authorization: Bearer kirichess_pat_… à chaque requête. Il y a exactement deux portées. Un jeton ne porte jamais de droits admin ni 2FA, même si le compte en a. Jusqu'à 10 jetons peuvent être actifs en même temps. Un jeton dure 90 jours, sauf si vous choisissez une autre durée entre 1 et 365 jours, et vous pouvez le révoquer plus tôt depuis la carte Jetons d'API de votre page de profil.

Après kirichess_pat_ viennent 43 caractères de l'alphabet base64 sûr pour les URL (A–Z, a–z, 0–9, trait d'union, tiret bas), puis 6 caractères de somme de contrôle. La somme est le CRC-32 (IEEE) de ces 43 caractères, écrit en 6 chiffres en base 62 dans l'alphabet 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz, complété à gauche par des zéros. Un scanner de secrets peut rejeter une chaîne qui échoue à ce contrôle sans appeler ce serveur.

• read, identité, vos parties, relectures terminées, vos défis ouverts, classements du groupe des bots, annonces de bots.
• play, créer des parties et des défis non classés, jouer et abandonner, et rejoindre l'appariement du groupe des bots via le hub. Play implique read au moment de l'émission.

Votre moteur s'exécute dans le processus qui appelle cette API. Les origines navigateur autres que ce site restent bloquées ; CORS n'est pas élargi pour cette API.

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

POST /api/v1/games ne crée qu'une partie en solo, les deux sièges sont vous, pour exercer le moteur de bout en bout. Un opponentId qui désigne quelqu'un d'autre est rejeté : les parties appariées passent toujours par POST /api/v1/challenges ou le groupe des bots. La mesure classée se fait sur demande : connectez-vous au hub de partie avec le même jeton et faites JoinQueue avec un préréglage officiel (bounty1, burn1, steal1, steal2, burn2, steal3). Cela est réaffecté à bot:{preset} et ne se mélange jamais au Glicko humain.

Le groupe de bots est une courtoisie envers les auteurs de bots honnêtes, pas une barrière technique : un script connecté avec le mot de passe d'un compte est indiscernable d'un navigateur au moment de la file d'attente et se retrouve dans le groupe humain. Jouer dans le groupe humain depuis un script est contraire aux règles, quel que soit l'identifiant utilisé pour s'authentifier.

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}'

Connectez-vous à wss://api.kirichess.com/hubs/game. Un bot s'authentifie de la même façon que partout ailleurs dans cette API : envoyez Authorization: Bearer kirichess_pat_… lors de la demande de connexion. Le site lui-même place un JWT de session de courte durée dans la requête access_token, parce qu'un navigateur ne peut pas définir d'en-tête lors d'un handshake WebSocket. Le serveur accepte encore un jeton kirichess_pat_… dans cette requête. N'en mettez pas : il est consigné dans le journal du proxy de Fly, dans le journal des requêtes de Cloudflare, et dans l'URL de requête capturée par Sentry.

Méthodes joueur : JoinQueue, SubmitMove, Resign, OfferDraw, RespondDraw et LeaveQueue. Événements : MatchFound, MovePlayed, GameEnded, DrawOffered, DrawDeclined, OpponentDisconnected et OpponentReconnected. WatchChallenge et UnwatchChallenge abonnent cette connexion à un défi que vous avez créé ; OfferRematch et AcceptRematch poursuivent une partie terminée. JoinAsSpectator reste anonyme. Une boucle qui fonctionne : se connecter, JoinQueue, attendre MatchFound, puis JoinGame(gameId) pour obtenir la position actuelle et s'abonner aux événements de cette partie avant d'appeler SubmitMove ou de réagir à MovePlayed ; sans JoinGame, aucun événement MovePlayed n'arrive. Les coups d'une partie appariée par le hub peuvent aussi être envoyés via POST /api/v1/games/{id}/moves plutôt que par le hub, si c'est plus simple pour votre client.