Sign in

v3

latestOpenAPI 3.1.0AGPL-3.0-or-later2026-07-311871891.1 MB
Bulk pairings

Create a bulk pairing

Schedule many games at once, up to 24h in advance. OAuth tokens are required for all paired players, with the challenge:write scope. You can schedule up to 500 games every 10 minutes. Contact us if you need higher limits. If games have a real-time clock, each player must have only one pairing. For correspondence games, players can have multiple pairings within the same bulk.

The entire bulk is rejected if:

  • a token is missing
  • a token is present more than once (except in correspondence)
  • a token lacks the challenge:write scope
  • a player account is closed
  • a player is paired more than once (except in correspondence)
  • a bulk is already scheduled to start at the same time with the same player
  • you have 20 scheduled bulks
  • you have 1000 scheduled games

Partial bulks are never created. Either it all fails, or it all succeeds. When it fails, it does so with an error message explaining the issue. Failed bulks are not counted in the rate limiting, they are free. Fix the issues, manually or programmatically, then retry to schedule the bulk. A successful bulk creation returns a JSON bulk document. Its ID can be used for further operations.

post/api/bulk-pairing

Response

The bulk pairing has been successfully created.

idstring required
variant'standard' | 'chess960' | 'crazyhouse' | 'antichess' | 'atomic' | 'horde' | 'kingOfTheHill' | 'racingKings' | 'threeCheck' | 'fromPosition' required
pairAtinteger required
pairedAtinteger nullable required
ratedboolean required
startClocksAtinteger required
scheduledAtinteger required

Example response

{
  "id": "RVAcwgg7",
  "games": [
    {
      "id": "NKop9IyD",
      "black": "lizen1",
      "white": "thibault"
    },
    {
      "id": "KT8374ut",
      "black": "lizen3",
      "white": "lizen2"
    },
    {
      "id": "wInQr8Sk",
      "black": "lizen5",
      "white": "lizen4"
    }
  ],
  "variant": "standard",
  "clock": {
    "increment": 0,
    "limit": 300
  },
  "pairAt": 1612289869919,
  "pairedAt": null,
  "rated": false,
  "startClocksAt": 1612200422971,
  "scheduledAt": 1612203514628
}