lichess-org · fitztrev · May 16, 2025 · May 16, 2025
diff --git a/doc/specs/examples/challenges-acceptChallenge.json b/doc/specs/examples/challenges-acceptChallenge.json
@@ -0,0 +1,3 @@
+{
+  "ok": true
+}
diff --git a/doc/specs/examples/challenges-addTimeToOpponent.json b/doc/specs/examples/challenges-addTimeToOpponent.json
@@ -0,0 +1,3 @@
+{
+  "ok": true
+}
diff --git a/doc/specs/examples/challenges-adminChallengeTokens.json b/doc/specs/examples/challenges-adminChallengeTokens.json
@@ -0,0 +1,5 @@
+{
+  "bobby": "lip_UApWGQEPAy2fn2sneRLL",
+  "boris": "lip_OqjzF0daIQ42uEOfUmPO",
+  "mary": "lip_p40VbmcuQ54qnyDtpSSX"
+}
diff --git a/doc/specs/examples/challenges-cancelChallenge.json b/doc/specs/examples/challenges-cancelChallenge.json
@@ -0,0 +1,3 @@
+{
+  "ok": true
+}
diff --git a/doc/specs/examples/challenges-challengeAi.json b/doc/specs/examples/challenges-challengeAi.json
@@ -0,0 +1,21 @@
+{
+  "id": "FLuFXFzs",
+  "variant": {
+    "key": "standard",
+    "name": "Standard",
+    "short": "Std"
+  },
+  "speed": "correspondence",
+  "perf": "correspondence",
+  "rated": false,
+  "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
+  "turns": 0,
+  "source": "ai",
+  "status": {
+    "id": 20,
+    "name": "started"
+  },
+  "createdAt": 1747312530755,
+  "player": "white",
+  "fullId": "FLuFXFzs4NSG"
+}
diff --git a/doc/specs/examples/challenges-createChallenge.json b/doc/specs/examples/challenges-createChallenge.json
@@ -0,0 +1,35 @@
+{
+  "id": "1jqMGJOv",
+  "url": "https://lichess.org/1jqMGJOv",
+  "status": "created",
+  "challenger": {
+    "id": "bobby",
+    "name": "Bobby",
+    "rating": 1612,
+    "title": null
+  },
+  "destUser": {
+    "id": "mary",
+    "name": "Mary",
+    "rating": 1064,
+    "title": null,
+    "flair": "objects.notebook"
+  },
+  "variant": {
+    "key": "standard",
+    "name": "Standard",
+    "short": "Std"
+  },
+  "rated": false,
+  "speed": "correspondence",
+  "timeControl": {
+    "type": "unlimited"
+  },
+  "color": "random",
+  "finalColor": "white",
+  "perf": {
+    "icon": "",
+    "name": "Correspondence"
+  },
+  "direction": "out"
+}
diff --git a/doc/specs/examples/challenges-declineChallenge.json b/doc/specs/examples/challenges-declineChallenge.json
@@ -0,0 +1,3 @@
+{
+  "ok": true
+}
diff --git a/doc/specs/examples/challenges-listYourChallenges.json b/doc/specs/examples/challenges-listYourChallenges.json
@@ -0,0 +1,40 @@
+{
+  "in": [
+    {
+      "id": "1jqMGJOv",
+      "url": "https://lichess.org/1jqMGJOv",
+      "status": "created",
+      "challenger": {
+        "id": "bobby",
+        "name": "Bobby",
+        "rating": 1612,
+        "title": null
+      },
+      "destUser": {
+        "id": "mary",
+        "name": "Mary",
+        "rating": 1064,
+        "title": null,
+        "flair": "objects.notebook"
+      },
+      "variant": {
+        "key": "standard",
+        "name": "Standard",
+        "short": "Std"
+      },
+      "rated": false,
+      "speed": "correspondence",
+      "timeControl": {
+        "type": "unlimited"
+      },
+      "color": "random",
+      "finalColor": "white",
+      "perf": {
+        "icon": "",
+        "name": "Correspondence"
+      },
+      "direction": "in"
+    }
+  ],
+  "out": []
+}
diff --git a/doc/specs/examples/challenges-openEndedChallenge.json b/doc/specs/examples/challenges-openEndedChallenge.json
@@ -0,0 +1,26 @@
+{
+  "id": "XaP00j5r",
+  "url": "https://lichess.org/XaP00j5r",
+  "status": "created",
+  "challenger": null,
+  "destUser": null,
+  "variant": {
+    "key": "standard",
+    "name": "Standard",
+    "short": "Std"
+  },
+  "rated": false,
+  "speed": "correspondence",
+  "timeControl": {
+    "type": "unlimited"
+  },
+  "color": "random",
+  "finalColor": "black",
+  "perf": {
+    "icon": "",
+    "name": "Correspondence"
+  },
+  "open": {},
+  "urlWhite": "https://lichess.org/XaP00j5r?color=white",
+  "urlBlack": "https://lichess.org/XaP00j5r?color=black"
+}
diff --git a/doc/specs/examples/challenges-showOneChallenge.json b/doc/specs/examples/challenges-showOneChallenge.json
@@ -0,0 +1,35 @@
+{
+  "id": "1jqMGJOv",
+  "url": "https://lichess.org/1jqMGJOv",
+  "status": "created",
+  "challenger": {
+    "id": "bobby",
+    "name": "Bobby",
+    "rating": 1612,
+    "title": null
+  },
+  "destUser": {
+    "id": "mary",
+    "name": "Mary",
+    "rating": 1064,
+    "title": null,
+    "flair": "objects.notebook"
+  },
+  "variant": {
+    "key": "standard",
+    "name": "Standard",
+    "short": "Std"
+  },
+  "rated": false,
+  "speed": "correspondence",
+  "timeControl": {
+    "type": "unlimited"
+  },
+  "color": "random",
+  "finalColor": "white",
+  "perf": {
+    "icon": "",
+    "name": "Correspondence"
+  },
+  "direction": "in"
+}
diff --git a/doc/specs/examples/challenges-startClocks.json b/doc/specs/examples/challenges-startClocks.json
@@ -0,0 +1,3 @@
+{
+  "ok": true
+}
diff --git a/doc/specs/schemas/ChallengeEvent.yaml b/doc/specs/schemas/ChallengeEvent.yaml
@@ -6,9 +6,4 @@ properties:
   challenge:
     $ref: "./ChallengeJson.yaml"
   compat:
-    type: object
-    properties:
-      bot:
-        type: boolean
-      board:
-        type: boolean
+    $ref: "./GameCompat.yaml"
diff --git a/doc/specs/schemas/ChallengeOpenJson.yaml b/doc/specs/schemas/ChallengeOpenJson.yaml
@@ -62,21 +62,3 @@ required:
   - urlWhite
   - urlBlack
   - open
-example:
-  {
-    "id": "3gH5lybT",
-    "url": "https://lichess.org/3gH5lybT",
-    "status": "created",
-    "challenger": null,
-    "destUser": null,
-    "variant": { "key": "standard", "name": "Standard", "short": "Std" },
-    "rated": false,
-    "speed": "rapid",
-    "timeControl": { "type": "clock", "limit": 600, "increment": 5, "show": "10+5" },
-    "color": "random",
-    "finalColor": "black",
-    "perf": { "icon": "", "name": "Rapid" },
-    "open": {},
-    "urlWhite": "https://lichess.org/3gH5lybT?color=white",
-    "urlBlack": "https://lichess.org/3gH5lybT?color=black",
-  }
diff --git a/doc/specs/schemas/ChallengeUser.yaml b/doc/specs/schemas/ChallengeUser.yaml
@@ -1,11 +1,26 @@
-allOf:
-  - $ref: "./LightUser.yaml"
+type: object
 properties:
+  id:
+    type: string
+  name:
+    type: string
   rating:
     type: number
+  title:
+    oneOf:
+      - $ref: "./Title.yaml"
+      - type: "null"
+  flair:
+    $ref: "./Flair.yaml"
+  patron:
+    type: boolean
   provisional:
     type: boolean
   online:
     type: boolean
   lag:
     type: number
+
+required:
+  - id
+  - name
diff --git a/doc/specs/schemas/GameCompat.yaml b/doc/specs/schemas/GameCompat.yaml
@@ -0,0 +1,9 @@
+type: object
+
+properties:
+  bot:
+    type: boolean
+    description: Compatible with Bot API
+  board:
+    type: boolean
+    description: Compatible with Board API
diff --git a/doc/specs/schemas/GameEventInfo.yaml b/doc/specs/schemas/GameEventInfo.yaml
@@ -50,12 +50,7 @@ properties:
   secondsLeft:
     type: integer
   compat:
-    type: object
-    properties:
-      bot:
-        type: boolean
-      board:
-        type: boolean
+    $ref: "./GameCompat.yaml"
   id:
     type: string
 

diff --git a/doc/specs/tags/challenges/api-challenge-ai.yaml b/doc/specs/tags/challenges/api-challenge-ai.yaml
@@ -56,6 +56,8 @@ post:
               $ref: "../../schemas/VariantKey.yaml"
             fen:
               $ref: "../../schemas/FromPositionFEN.yaml"
+          required:
+            - level
   responses:
     "201":
       description: The game with Lichess AI was successfully started.
@@ -67,7 +69,45 @@ post:
       content:
         application/json:
           schema:
-            $ref: "../../schemas/GameJson.yaml"
+            properties:
+              id:
+                type: string
+                minLength: 8
+                maxLength: 8
+              variant:
+                $ref: "../../schemas/Variant.yaml"
+              speed:
+                $ref: "../../schemas/Speed.yaml"
+              perf:
+                $ref: "../../schemas/PerfType.yaml"
+              rated:
+                type: boolean
+              fen:
+                type: string
+              turns:
+                type: integer
+              source:
+                $ref: "../../schemas/GameSource.yaml"
+              status:
+                type: object
+                properties:
+                  id:
+                    type: integer
+                    enum: [10, 20, 25, 30, 31, 32, 33, 34, 35, 36, 37, 38, 60]
+                  name:
+                    $ref: "../../schemas/GameStatus.yaml"
+              createdAt:
+                type: number
+                format: int64
+              player:
+                type: string
+                enum: ["white", "black"]
+              fullId:
+                type: string
+                minLength: 12
+                maxLength: 12
+          example:
+            $ref: "../../examples/challenges-challengeAi.json"
     "400":
       description: The creation of a game with Lichess AI failed.
       content:

diff --git a/doc/specs/tags/challenges/api-challenge-challengeId-accept.yaml b/doc/specs/tags/challenges/api-challenge-challengeId-accept.yaml
@@ -27,6 +27,8 @@ post:
         application/json:
           schema:
             $ref: "../../schemas/Ok.yaml"
+          example:
+            $ref: "../../examples/challenges-acceptChallenge.json"
     "404":
       description: The challenge to accept was not found.
       content:

diff --git a/doc/specs/tags/challenges/api-challenge-challengeId-cancel.yaml b/doc/specs/tags/challenges/api-challenge-challengeId-cancel.yaml
@@ -33,6 +33,8 @@ post:
         application/json:
           schema:
             $ref: "../../schemas/Ok.yaml"
+          example:
+            $ref: "../../examples/challenges-cancelChallenge.json"
     "404":
       description: The challenge to cancel was not found.
       content:

diff --git a/doc/specs/tags/challenges/api-challenge-challengeId-decline.yaml b/doc/specs/tags/challenges/api-challenge-challengeId-decline.yaml
@@ -49,6 +49,8 @@ post:
         application/json:
           schema:
             $ref: "../../schemas/Ok.yaml"
+          example:
+            $ref: "../../examples/challenges-declineChallenge.json"
     "404":
       description: The challenge to decline was not found.
       content:

diff --git a/doc/specs/tags/challenges/api-challenge-gameId-start-clocks.yaml b/doc/specs/tags/challenges/api-challenge-gameId-start-clocks.yaml
@@ -41,3 +41,5 @@ post:
         application/json:
           schema:
             $ref: "../../schemas/Ok.yaml"
+          example:
+            $ref: "../../examples/challenges-startClocks.json"
diff --git a/doc/specs/tags/challenges/api-challenge-id-show.yaml b/doc/specs/tags/challenges/api-challenge-id-show.yaml
@@ -26,3 +26,5 @@ get:
         application/json:
           schema:
             $ref: "../../schemas/ChallengeJson.yaml"
+          example:
+            $ref: "../../examples/challenges-showOneChallenge.json"
diff --git a/doc/specs/tags/challenges/api-challenge-open.yaml b/doc/specs/tags/challenges/api-challenge-open.yaml
@@ -90,6 +90,8 @@ post:
         application/json:
           schema:
             $ref: "../../schemas/ChallengeOpenJson.yaml"
+          example:
+            $ref: "../../examples/challenges-openEndedChallenge.json"
     "400":
       description: The creation of the challenge failed.
       content:

diff --git a/doc/specs/tags/challenges/api-challenge-username.yaml b/doc/specs/tags/challenges/api-challenge-username.yaml
@@ -95,6 +95,8 @@ post:
         application/json:
           schema:
             $ref: "../../schemas/ChallengeJson.yaml"
+          example:
+            $ref: "../../examples/challenges-createChallenge.json"
     "400":
       description: The creation of the challenge failed.
       content:

diff --git a/doc/specs/tags/challenges/api-challenge.yaml b/doc/specs/tags/challenges/api-challenge.yaml
@@ -30,3 +30,5 @@ get:
                 description: Outgoing challenges i.e. created by you
                 items:
                   $ref: "../../schemas/ChallengeJson.yaml"
+          example:
+            $ref: "../../examples/challenges-listYourChallenges.json"