{
    "openapi": "3.1.0",
    "info": {
        "title": "FlipSight Bot API",
        "version": "2.3.0",
        "description": "Bot API v2: registered bots receive their state from the event stream only (GET /flipsight_api/bot-stream) and send actions to /flipsight/bot_match_api.php. agent_poll is removed on 2026-11-22 00:00 (UTC+9; 2026-11-21 15:00 UTC) and returns HTTP 410 from then on: reconnect the stream to resync. From 2026-11-21 23:40 (UTC+9), registered bots that call agent_poll or reconnect more than 10 times in 10 minutes are left out of automatic matching."
    },
    "servers": [
        {
            "url": "https://othelloclub.com"
        }
    ],
    "components": {
        "securitySchemes": {
            "BotToken": {
                "type": "http",
                "scheme": "bearer"
            }
        },
        "schemas": {
            "Bot": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "string"
                    },
                    "supported_games": {
                        "type": "array",
                        "minItems": 1,
                        "items": {
                            "type": "string",
                            "enum": [
                                "std",
                                "anti",
                                "octagon",
                                "grand",
                                "reversi"
                            ]
                        }
                    },
                    "auto_match": {
                        "type": "boolean"
                    },
                    "auto_games": {
                        "type": [
                            "array",
                            "null"
                        ],
                        "items": {
                            "type": "string",
                            "enum": [
                                "std",
                                "anti",
                                "octagon",
                                "grand",
                                "reversi"
                            ]
                        }
                    },
                    "owner_id": {
                        "type": "string"
                    },
                    "owner_name": {
                        "type": "string"
                    },
                    "is_builtin": {
                        "type": "boolean"
                    },
                    "online": {
                        "type": "boolean"
                    },
                    "disabled": {
                        "type": "boolean"
                    },
                    "deleted": {
                        "type": "boolean"
                    },
                    "engine_level": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "rating": {
                        "type": "object"
                    },
                    "environment": {
                        "oneOf": [
                            {
                                "type": "object",
                                "properties": {
                                    "cpu": {
                                        "type": [
                                            "string",
                                            "null"
                                        ]
                                    },
                                    "engine": {
                                        "type": [
                                            "string",
                                            "null"
                                        ]
                                    },
                                    "os": {
                                        "type": [
                                            "string",
                                            "null"
                                        ]
                                    },
                                    "practice": {
                                        "type": "boolean"
                                    },
                                    "engine_threads": {
                                        "type": [
                                            "integer",
                                            "null"
                                        ]
                                    },
                                    "hash_mb": {
                                        "type": [
                                            "number",
                                            "null"
                                        ]
                                    },
                                    "ponder": {
                                        "type": [
                                            "boolean",
                                            "null"
                                        ]
                                    }
                                }
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "env": {
                        "oneOf": [
                            {
                                "type": "object",
                                "properties": {
                                    "cpu": {
                                        "type": [
                                            "string",
                                            "null"
                                        ]
                                    },
                                    "engine_threads": {
                                        "type": [
                                            "integer",
                                            "null"
                                        ]
                                    },
                                    "hash_mb": {
                                        "type": [
                                            "number",
                                            "null"
                                        ]
                                    },
                                    "hash_mb_reported": {
                                        "type": [
                                            "number",
                                            "null"
                                        ]
                                    },
                                    "hash_mb_override": {
                                        "type": [
                                            "number",
                                            "null"
                                        ]
                                    },
                                    "ponder": {
                                        "type": [
                                            "boolean",
                                            "null"
                                        ]
                                    },
                                    "ponder_reported": {
                                        "type": [
                                            "boolean",
                                            "null"
                                        ]
                                    },
                                    "ponder_override": {
                                        "type": [
                                            "boolean",
                                            "null"
                                        ]
                                    },
                                    "cpu_override": {
                                        "type": [
                                            "string",
                                            "null"
                                        ]
                                    },
                                    "engine_threads_override": {
                                        "type": [
                                            "integer",
                                            "null"
                                        ]
                                    },
                                    "cpu_reported": {
                                        "type": [
                                            "string",
                                            "null"
                                        ]
                                    },
                                    "engine_threads_reported": {
                                        "type": [
                                            "integer",
                                            "null"
                                        ]
                                    }
                                }
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "photo": {
                        "type": "string"
                    },
                    "bio": {
                        "type": "string"
                    },
                    "registered_at": {
                        "type": "string"
                    },
                    "registered_at_ts": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    }
                }
            },
            "Match": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "kind": {
                        "type": "string",
                        "enum": [
                            "human"
                        ]
                    },
                    "record": {
                        "$ref": "#/components/schemas/GameRecord",
                        "description": "Only in your own bot's view of a finished or aborted match (the last match event)."
                    },
                    "room_id": {
                        "type": "integer"
                    },
                    "round_no": {
                        "type": "integer"
                    },
                    "room_created_at": {
                        "type": "string"
                    },
                    "bot_a": {
                        "type": "integer"
                    },
                    "bot_b": {
                        "type": "integer"
                    },
                    "game_mode": {
                        "type": "string"
                    },
                    "time_limit_sec": {
                        "type": "integer"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "pending",
                            "running",
                            "finished",
                            "aborted",
                            "rejected",
                            "expired"
                        ]
                    },
                    "state": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/State"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "auto": {
                        "type": "boolean"
                    },
                    "expires_ms": {
                        "type": "integer"
                    },
                    "ranked": {
                        "type": "boolean"
                    },
                    "rating_applied": {
                        "type": "boolean"
                    },
                    "rating_before": {
                        "type": "array",
                        "items": {
                            "type": [
                                "number",
                                "string",
                                "null"
                            ]
                        }
                    },
                    "rating_after": {
                        "type": "array",
                        "items": {
                            "type": [
                                "number",
                                "string",
                                "null"
                            ]
                        }
                    },
                    "created_at": {
                        "type": "string"
                    }
                }
            },
            "GameRecord": {
                "type": "object",
                "required": [
                    "format",
                    "kind",
                    "id",
                    "result",
                    "legs"
                ],
                "description": "One finished game from your bot's side. Moves use the site notation: two characters per move (columns a-j, rows 1-9, 0 for the tenth row), pa for a pass; squares are row*board_size+column, -1 for a pass.",
                "properties": {
                    "format": {
                        "type": "integer",
                        "const": 1
                    },
                    "kind": {
                        "type": "string",
                        "enum": [
                            "bot",
                            "human"
                        ]
                    },
                    "id": {
                        "type": "integer"
                    },
                    "url": {
                        "type": "string"
                    },
                    "room_id": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "round_no": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "game_mode": {
                        "type": "string",
                        "enum": [
                            "std",
                            "anti",
                            "octagon",
                            "grand",
                            "reversi"
                        ]
                    },
                    "opening_mode": {
                        "type": "string"
                    },
                    "board_size": {
                        "type": "integer",
                        "enum": [
                            8,
                            10
                        ]
                    },
                    "time_limit_sec": {
                        "type": "integer"
                    },
                    "auto": {
                        "type": "boolean"
                    },
                    "ranked": {
                        "type": "boolean"
                    },
                    "rating_applied": {
                        "type": "boolean"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "finished",
                            "aborted"
                        ]
                    },
                    "finish_reason": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "result": {
                        "type": "string",
                        "enum": [
                            "win",
                            "loss",
                            "draw",
                            "void"
                        ]
                    },
                    "started_ms": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "finished_ms": {
                        "type": "integer"
                    },
                    "updated_ms": {
                        "type": "integer"
                    },
                    "me": {
                        "type": "object",
                        "properties": {
                            "kind": {
                                "type": "string",
                                "enum": [
                                    "bot",
                                    "human",
                                    "guest"
                                ]
                            },
                            "bot_id": {
                                "type": "integer"
                            },
                            "player_id": {
                                "type": "string"
                            },
                            "builtin": {
                                "type": "boolean"
                            },
                            "name": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "engine": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "rating_before": {
                                "type": [
                                    "number",
                                    "null"
                                ]
                            },
                            "rating_after": {
                                "type": [
                                    "number",
                                    "null"
                                ]
                            }
                        }
                    },
                    "opponent": {
                        "type": "object",
                        "properties": {
                            "kind": {
                                "type": "string",
                                "enum": [
                                    "bot",
                                    "human",
                                    "guest"
                                ]
                            },
                            "bot_id": {
                                "type": "integer"
                            },
                            "player_id": {
                                "type": "string"
                            },
                            "builtin": {
                                "type": "boolean"
                            },
                            "name": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "engine": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "rating_before": {
                                "type": [
                                    "number",
                                    "null"
                                ]
                            },
                            "rating_after": {
                                "type": [
                                    "number",
                                    "null"
                                ]
                            }
                        }
                    },
                    "discs": {
                        "type": [
                            "array",
                            "null"
                        ],
                        "items": {
                            "type": "integer"
                        }
                    },
                    "opening": {
                        "type": "string"
                    },
                    "opening_squares": {
                        "type": "array",
                        "items": {
                            "type": "integer"
                        }
                    },
                    "opening_colors": {
                        "type": "string"
                    },
                    "legs": {
                        "type": "array",
                        "maxItems": 2,
                        "items": {
                            "type": "object",
                            "properties": {
                                "my_color": {
                                    "type": "string",
                                    "enum": [
                                        "B",
                                        "W"
                                    ]
                                },
                                "status": {
                                    "type": "string"
                                },
                                "discs": {
                                    "type": "array",
                                    "items": {
                                        "type": "integer"
                                    }
                                },
                                "result_discs": {
                                    "type": "array",
                                    "items": {
                                        "type": "integer"
                                    }
                                },
                                "colors": {
                                    "type": "string"
                                },
                                "moves": {
                                    "type": "string"
                                },
                                "squares": {
                                    "type": "array",
                                    "items": {
                                        "type": "integer"
                                    }
                                },
                                "at_ms": {
                                    "type": "array",
                                    "items": {
                                        "type": [
                                            "integer",
                                            "null"
                                        ]
                                    }
                                },
                                "used_ms": {
                                    "type": "array",
                                    "items": {
                                        "type": [
                                            "integer",
                                            "null"
                                        ]
                                    }
                                },
                                "left_ms": {
                                    "type": "array",
                                    "items": {
                                        "type": [
                                            "integer",
                                            "null"
                                        ]
                                    }
                                },
                                "evals": {
                                    "type": "array",
                                    "items": {
                                        "type": [
                                            "number",
                                            "null"
                                        ]
                                    },
                                    "description": "Optional: the eval each mover sent with its move, in discs from the mover's side; null where none was sent. Left out when no move in the leg had one."
                                }
                            }
                        }
                    }
                }
            },
            "State": {
                "type": "object",
                "properties": {
                    "version": {
                        "type": "integer",
                        "const": 1
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "finished",
                            "aborted"
                        ]
                    },
                    "game_mode": {
                        "type": "string",
                        "enum": [
                            "std",
                            "anti",
                            "octagon",
                            "grand",
                            "reversi"
                        ]
                    },
                    "board_size": {
                        "type": "integer",
                        "enum": [
                            8,
                            10
                        ]
                    },
                    "blocked_squares": {
                        "type": "array",
                        "items": {
                            "type": "integer"
                        }
                    },
                    "time_limit_sec": {
                        "type": "integer"
                    },
                    "revision": {
                        "type": "integer"
                    },
                    "legs": {
                        "type": "array",
                        "minItems": 1,
                        "maxItems": 2,
                        "items": {
                            "$ref": "#/components/schemas/Leg"
                        }
                    },
                    "totals": {
                        "type": "array",
                        "minItems": 2,
                        "maxItems": 2,
                        "items": {
                            "type": "integer"
                        }
                    },
                    "winner": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "enum": [
                            0,
                            1,
                            null
                        ]
                    },
                    "opening_moves": {
                        "type": "array",
                        "items": {
                            "type": "integer"
                        }
                    },
                    "opening_history": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/HistoryMove"
                        }
                    },
                    "started_ms": {
                        "type": "integer"
                    },
                    "finished_ms": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "finish_reason": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                }
            },
            "Leg": {
                "type": "object",
                "properties": {
                    "board": {
                        "oneOf": [
                            {
                                "type": "array",
                                "minItems": 64,
                                "maxItems": 64,
                                "items": {
                                    "type": "integer",
                                    "enum": [
                                        0,
                                        1,
                                        2
                                    ]
                                }
                            },
                            {
                                "type": "array",
                                "minItems": 100,
                                "maxItems": 100,
                                "items": {
                                    "type": "integer",
                                    "enum": [
                                        0,
                                        1,
                                        2
                                    ]
                                }
                            }
                        ]
                    },
                    "legal_moves": {
                        "type": "array",
                        "items": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 99
                        }
                    },
                    "placed": {
                        "type": "object"
                    },
                    "turn": {
                        "type": "integer",
                        "enum": [
                            1,
                            2
                        ]
                    },
                    "black_participant": {
                        "type": "integer",
                        "enum": [
                            0,
                            1
                        ]
                    },
                    "clocks_ms": {
                        "type": "array",
                        "minItems": 2,
                        "maxItems": 2,
                        "items": {
                            "type": "number"
                        }
                    },
                    "turn_started_ms": {
                        "type": "integer"
                    },
                    "revision": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "history": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/HistoryMove"
                        }
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "finished",
                            "timeout",
                            "stopped"
                        ]
                    },
                    "result_discs": {
                        "type": "array",
                        "minItems": 2,
                        "maxItems": 2,
                        "items": {
                            "type": "integer"
                        },
                        "description": "Optional timeout adjudicated scores in black/white order. When present, use instead of discs for totals; discs and board retain the actual position."
                    },
                    "discs": {
                        "type": "array",
                        "minItems": 2,
                        "maxItems": 2,
                        "items": {
                            "type": "integer"
                        }
                    },
                    "finished_ms": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    }
                }
            },
            "HistoryMove": {
                "type": "object",
                "properties": {
                    "color": {
                        "type": "integer",
                        "enum": [
                            1,
                            2
                        ]
                    },
                    "move": {
                        "type": "integer",
                        "minimum": -1,
                        "maximum": 99
                    },
                    "at_ms": {
                        "type": "integer"
                    },
                    "eval": {
                        "type": "number",
                        "minimum": -100,
                        "maximum": 100,
                        "description": "Optional (2026-11-21): the evaluation the mover sent with agent_move, in discs from the mover's side (std, anti and reversi -64..64, grand -100..100, octagon -88..88). Sent to everyone during the game."
                    }
                }
            },
            "StreamHello": {
                "type": "object",
                "required": [
                    "type",
                    "bot_id",
                    "server_now_ms"
                ],
                "properties": {
                    "type": {
                        "const": "hello"
                    },
                    "bot_id": {
                        "type": "integer"
                    },
                    "server_now_ms": {
                        "type": "integer"
                    },
                    "state_follows": {
                        "type": "boolean",
                        "const": true,
                        "description": "Present unless ?state=0: a state event follows."
                    },
                    "api": {
                        "type": "integer",
                        "const": 2,
                        "description": "Present unless ?state=0: bot API v2 (state from the stream only)."
                    }
                }
            },
            "StreamState": {
                "type": "object",
                "required": [
                    "type",
                    "ok",
                    "server_now_ms"
                ],
                "description": "Right after hello on every connection (not with ?state=0): your bot and your ongoing games only (the same content as agent_poll with \"scope\": \"active\", with type and view added; no other bots, no finished games). Use it as the current state. With \"ok\": false (state unavailable) reconnect after a short delay; after \"invalid bot credential\" the stream closes.",
                "properties": {
                    "type": {
                        "const": "state"
                    },
                    "view": {
                        "const": "agent"
                    },
                    "ok": {
                        "type": "boolean"
                    },
                    "error": {
                        "type": "string"
                    },
                    "scope": {
                        "const": "active"
                    },
                    "bot": {
                        "$ref": "#/components/schemas/Bot"
                    },
                    "matches": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Match"
                        }
                    },
                    "server_now_ms": {
                        "type": "integer"
                    }
                }
            },
            "StreamMatch": {
                "type": "object",
                "required": [
                    "type",
                    "match",
                    "server_now_ms"
                ],
                "description": "One of your matches changed. With view \"agent\" the match is your own view, the same object as in agent_poll matches: replace the match with the same id or add it, and drop a late one whose state.revision (games against people: room_created_at, round_no, revision) is lower. Bot matches, invitations and games against people all come with view \"agent\" (games against people only when your view changed). Only the older format (?state=0) sends events without view (invitations, and games against people as {id: -room_id, kind: \"human\", room_id}). When a match ends, your view also carries record (GameRecord); save it to keep the game.",
                "properties": {
                    "type": {
                        "const": "match"
                    },
                    "view": {
                        "const": "agent"
                    },
                    "match": {
                        "$ref": "#/components/schemas/Match"
                    },
                    "server_now_ms": {
                        "type": "integer"
                    }
                }
            },
            "StreamPing": {
                "type": "object",
                "required": [
                    "type",
                    "server_now_ms"
                ],
                "description": "Keep-alive every 10 seconds. No line for 15 seconds means the stream is stuck: reconnect.",
                "properties": {
                    "type": {
                        "const": "ping"
                    },
                    "server_now_ms": {
                        "type": "integer"
                    }
                }
            },
            "StreamClosing": {
                "type": "object",
                "required": [
                    "type",
                    "reason",
                    "server_now_ms"
                ],
                "description": "Last line before the server closes the stream. overflow: too many unsent lines (64) piled up, the queued lines were dropped. server_shutdown: the server is restarting. For both, reconnect and catch up from state. replaced: the same token is in use somewhere else; do not reconnect at once, wait at least 30 s and longer if it happens again, and use each token in one place only. A stream can also end without this line (network drop): reconnect as usual.",
                "properties": {
                    "type": {
                        "const": "closing"
                    },
                    "reason": {
                        "type": "string",
                        "enum": [
                            "overflow",
                            "replaced",
                            "server_shutdown"
                        ]
                    },
                    "server_now_ms": {
                        "type": "integer"
                    }
                }
            }
        }
    },
    "paths": {
        "/flipsight/bot_match_api.php": {
            "post": {
                "tags": [
                    "Bot"
                ],
                "operationId": "botAction",
                "security": [
                    {
                        "BotToken": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "oneOf": [
                                    {
                                        "type": "object",
                                        "required": [
                                            "action",
                                            "environment"
                                        ],
                                        "properties": {
                                            "action": {
                                                "type": "string",
                                                "const": "agent_environment"
                                            },
                                            "environment": {
                                                "type": "object",
                                                "properties": {
                                                    "cpu": {
                                                        "type": [
                                                            "string",
                                                            "null"
                                                        ],
                                                        "maxLength": 120
                                                    },
                                                    "engine": {
                                                        "type": [
                                                            "string",
                                                            "null"
                                                        ],
                                                        "maxLength": 120
                                                    },
                                                    "os": {
                                                        "type": [
                                                            "string",
                                                            "null"
                                                        ],
                                                        "maxLength": 120
                                                    },
                                                    "engine_threads": {
                                                        "type": "integer",
                                                        "minimum": 1,
                                                        "maximum": 1024
                                                    },
                                                    "hash_mb": {
                                                        "type": [
                                                            "number",
                                                            "null"
                                                        ],
                                                        "minimum": 0,
                                                        "maximum": 1048576
                                                    },
                                                    "ponder": {
                                                        "type": [
                                                            "boolean",
                                                            "null"
                                                        ]
                                                    },
                                                    "practice": {
                                                        "type": "boolean"
                                                    }
                                                },
                                                "additionalProperties": false
                                            }
                                        }
                                    },
                                    {
                                        "type": "object",
                                        "required": [
                                            "action"
                                        ],
                                        "properties": {
                                            "action": {
                                                "type": "string",
                                                "const": "agent_challenge"
                                            },
                                            "target_id": {
                                                "type": "integer",
                                                "minimum": 1
                                            },
                                            "target_name": {
                                                "type": "string",
                                                "minLength": 2,
                                                "maxLength": 24
                                            },
                                            "game_mode": {
                                                "type": "string",
                                                "enum": [
                                                    "std",
                                                    "anti",
                                                    "octagon",
                                                    "grand",
                                                    "reversi"
                                                ],
                                                "default": "std"
                                            }
                                        },
                                        "anyOf": [
                                            {
                                                "required": [
                                                    "target_id"
                                                ]
                                            },
                                            {
                                                "required": [
                                                    "target_name"
                                                ]
                                            }
                                        ]
                                    },
                                    {
                                        "type": "object",
                                        "required": [
                                            "action",
                                            "match_id"
                                        ],
                                        "properties": {
                                            "action": {
                                                "type": "string",
                                                "const": "agent_accept"
                                            },
                                            "match_id": {
                                                "type": "integer",
                                                "minimum": 1
                                            }
                                        }
                                    },
                                    {
                                        "type": "object",
                                        "required": [
                                            "action",
                                            "match_id"
                                        ],
                                        "properties": {
                                            "action": {
                                                "type": "string",
                                                "const": "agent_reject"
                                            },
                                            "match_id": {
                                                "type": "integer",
                                                "minimum": 1
                                            }
                                        }
                                    },
                                    {
                                        "type": "object",
                                        "required": [
                                            "action",
                                            "match_id",
                                            "leg",
                                            "revision",
                                            "move"
                                        ],
                                        "properties": {
                                            "action": {
                                                "type": "string",
                                                "const": "agent_move"
                                            },
                                            "match_id": {
                                                "type": "integer",
                                                "not": {
                                                    "const": 0
                                                }
                                            },
                                            "round_no": {
                                                "type": "integer",
                                                "minimum": 0
                                            },
                                            "room_created_at": {
                                                "type": "string"
                                            },
                                            "leg": {
                                                "type": "integer",
                                                "enum": [
                                                    0,
                                                    1
                                                ]
                                            },
                                            "revision": {
                                                "type": "integer",
                                                "minimum": 0
                                            },
                                            "move": {
                                                "oneOf": [
                                                    {
                                                        "type": "integer",
                                                        "minimum": -1,
                                                        "maximum": 99
                                                    },
                                                    {
                                                        "type": "string",
                                                        "pattern": "^(?:[a-jA-J](?:10|[0-9])|[pP][aA](?:[sS][sS])?|[pP][sS]|--)$"
                                                    }
                                                ]
                                            },
                                            "eval": {
                                                "type": "number",
                                                "minimum": -100,
                                                "maximum": 100,
                                                "description": "Optional. Up to the playable squares of the game: std, anti and reversi -64..64, grand -100..100, octagon -88..88."
                                            }
                                        },
                                        "allOf": [
                                            {
                                                "if": {
                                                    "properties": {
                                                        "match_id": {
                                                            "maximum": -1
                                                        }
                                                    }
                                                },
                                                "then": {
                                                    "required": [
                                                        "round_no",
                                                        "room_created_at"
                                                    ],
                                                    "properties": {
                                                        "leg": {
                                                            "const": 0
                                                        },
                                                        "move": {
                                                            "oneOf": [
                                                                {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "maximum": 99
                                                                },
                                                                {
                                                                    "type": "string",
                                                                    "pattern": "^[a-jA-J](?:10|[0-9])$"
                                                                }
                                                            ]
                                                        }
                                                    }
                                                }
                                            }
                                        ]
                                    },
                                    {
                                        "type": "object",
                                        "required": [
                                            "action"
                                        ],
                                        "properties": {
                                            "action": {
                                                "type": "string",
                                                "const": "agent_games"
                                            },
                                            "since": {
                                                "type": "integer",
                                                "minimum": 0
                                            },
                                            "until": {
                                                "type": "integer",
                                                "minimum": 0
                                            },
                                            "max": {
                                                "type": "integer",
                                                "minimum": 1,
                                                "maximum": 300,
                                                "default": 100
                                            },
                                            "games": {
                                                "type": "array",
                                                "minItems": 1,
                                                "items": {
                                                    "type": "string",
                                                    "enum": [
                                                        "std",
                                                        "anti",
                                                        "octagon",
                                                        "grand",
                                                        "reversi"
                                                    ]
                                                }
                                            },
                                            "order": {
                                                "type": "string",
                                                "enum": [
                                                    "asc",
                                                    "desc"
                                                ],
                                                "default": "asc"
                                            }
                                        }
                                    },
                                    {
                                        "type": "object",
                                        "required": [
                                            "action"
                                        ],
                                        "properties": {
                                            "action": {
                                                "type": "string",
                                                "const": "agent_poll"
                                            },
                                            "environment": {
                                                "type": "object",
                                                "properties": {
                                                    "cpu": {
                                                        "type": [
                                                            "string",
                                                            "null"
                                                        ],
                                                        "maxLength": 120
                                                    },
                                                    "engine": {
                                                        "type": [
                                                            "string",
                                                            "null"
                                                        ],
                                                        "maxLength": 120
                                                    },
                                                    "os": {
                                                        "type": [
                                                            "string",
                                                            "null"
                                                        ],
                                                        "maxLength": 120
                                                    },
                                                    "engine_threads": {
                                                        "type": "integer",
                                                        "minimum": 1,
                                                        "maximum": 1024
                                                    },
                                                    "hash_mb": {
                                                        "type": [
                                                            "number",
                                                            "null"
                                                        ],
                                                        "minimum": 0,
                                                        "maximum": 1048576
                                                    },
                                                    "ponder": {
                                                        "type": [
                                                            "boolean",
                                                            "null"
                                                        ]
                                                    },
                                                    "practice": {
                                                        "type": "boolean"
                                                    }
                                                },
                                                "additionalProperties": false
                                            },
                                            "history": {
                                                "type": "string",
                                                "enum": [
                                                    "brief"
                                                ]
                                            },
                                            "scope": {
                                                "type": "string",
                                                "enum": [
                                                    "active"
                                                ]
                                            }
                                        },
                                        "deprecated": true,
                                        "description": "Removed on 2026-11-22 00:00 (UTC+9; 2026-11-21 15:00 UTC): from then on it returns HTTP 410 {\"ok\": false, \"error\": \"agent_poll was removed; use bot-stream\"}. Use the event stream for your state and reconnect it to resync. Until then it still answers, but from 2026-11-21 23:40 (UTC+9) a registered bot that called it in the last 10 minutes is left out of automatic matching."
                                    }
                                ]
                            },
                            "examples": {
                                "agent_environment": {
                                    "value": {
                                        "action": "agent_environment",
                                        "environment": {
                                            "cpu": "Apple M4",
                                            "engine": "MyEngine",
                                            "os": "Darwin",
                                            "engine_threads": 1,
                                            "hash_mb": 32,
                                            "ponder": false
                                        }
                                    }
                                },
                                "agent_challenge": {
                                    "value": {
                                        "action": "agent_challenge",
                                        "target_id": 2,
                                        "game_mode": "anti"
                                    }
                                },
                                "agent_accept": {
                                    "value": {
                                        "action": "agent_accept",
                                        "match_id": 123
                                    }
                                },
                                "agent_reject": {
                                    "value": {
                                        "action": "agent_reject",
                                        "match_id": 123
                                    }
                                },
                                "agent_move": {
                                    "value": {
                                        "action": "agent_move",
                                        "match_id": 123,
                                        "leg": 1,
                                        "revision": 0,
                                        "move": 2,
                                        "eval": 1.5
                                    }
                                },
                                "agent_games": {
                                    "value": {
                                        "action": "agent_games",
                                        "since": 1799913600000,
                                        "max": 100
                                    }
                                },
                                "agent_move_human": {
                                    "value": {
                                        "action": "agent_move",
                                        "match_id": -45,
                                        "leg": 0,
                                        "revision": 0,
                                        "move": "d3",
                                        "round_no": 1,
                                        "room_created_at": "2026-11-12 19:00:00"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK. agent_games answers application/x-ndjson: one GameRecord per line.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "server_now_ms"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "const": true
                                        },
                                        "server_now_ms": {
                                            "type": "integer"
                                        },
                                        "bot": {
                                            "$ref": "#/components/schemas/Bot"
                                        },
                                        "bots": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Bot"
                                            }
                                        },
                                        "record_bots": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Bot"
                                            }
                                        },
                                        "matches": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Match"
                                            }
                                        },
                                        "match_id": {
                                            "type": "integer"
                                        },
                                        "match": {
                                            "$ref": "#/components/schemas/Match"
                                        }
                                    }
                                }
                            },
                            "application/x-ndjson": {
                                "schema": {
                                    "$ref": "#/components/schemas/GameRecord"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "400",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "error",
                                        "server_now_ms"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "const": false
                                        },
                                        "error": {
                                            "type": "string"
                                        },
                                        "retry_after_sec": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Repeat-challenge cooldown in seconds; 0 means reserved matches must finish first."
                                        },
                                        "server_now_ms": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "401",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "error",
                                        "server_now_ms"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "const": false
                                        },
                                        "error": {
                                            "type": "string"
                                        },
                                        "retry_after_sec": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Repeat-challenge cooldown in seconds; 0 means reserved matches must finish first."
                                        },
                                        "server_now_ms": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "403",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "error",
                                        "server_now_ms"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "const": false
                                        },
                                        "error": {
                                            "type": "string"
                                        },
                                        "retry_after_sec": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Repeat-challenge cooldown in seconds; 0 means reserved matches must finish first."
                                        },
                                        "server_now_ms": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "405",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "error",
                                        "server_now_ms"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "const": false
                                        },
                                        "error": {
                                            "type": "string"
                                        },
                                        "retry_after_sec": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Repeat-challenge cooldown in seconds; 0 means reserved matches must finish first."
                                        },
                                        "server_now_ms": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "409",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "error",
                                        "server_now_ms"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "const": false
                                        },
                                        "error": {
                                            "type": "string"
                                        },
                                        "retry_after_sec": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Repeat-challenge cooldown in seconds; 0 means reserved matches must finish first."
                                        },
                                        "server_now_ms": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "410": {
                        "description": "410",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "error",
                                        "server_now_ms"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "const": false
                                        },
                                        "error": {
                                            "type": "string"
                                        },
                                        "retry_after_sec": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Repeat-challenge cooldown in seconds; 0 means reserved matches must finish first."
                                        },
                                        "server_now_ms": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "413": {
                        "description": "413",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "error",
                                        "server_now_ms"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "const": false
                                        },
                                        "error": {
                                            "type": "string"
                                        },
                                        "retry_after_sec": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Repeat-challenge cooldown in seconds; 0 means reserved matches must finish first."
                                        },
                                        "server_now_ms": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "429",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "error",
                                        "server_now_ms"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "const": false
                                        },
                                        "error": {
                                            "type": "string"
                                        },
                                        "retry_after_sec": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Repeat-challenge cooldown in seconds; 0 means reserved matches must finish first."
                                        },
                                        "server_now_ms": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "503",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "error",
                                        "server_now_ms"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "const": false
                                        },
                                        "error": {
                                            "type": "string"
                                        },
                                        "retry_after_sec": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Repeat-challenge cooldown in seconds; 0 means reserved matches must finish first."
                                        },
                                        "server_now_ms": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/flipsight_api/bot-stream": {
            "get": {
                "tags": [
                    "Bot"
                ],
                "operationId": "botStream",
                "security": [
                    {
                        "BotToken": []
                    }
                ],
                "summary": "Event stream (NDJSON, one JSON event per line)",
                "description": "Bot API v2: use the events as your state and send moves right away. Do not use agent_poll: to resync, reconnect the stream (every connection sends the full state again); the server also re-sends a missed update within a few seconds. Ignore event types and fields you do not know. Report engine details with agent_environment at start and when they change. One stream per bot token: opening a new one closes the previous one, so do not run the same token in two places. If the stream drops or sends nothing for 15 seconds, reconnect with a delay growing from 1 to 30 seconds. agent_poll is removed on 2026-11-22 00:00 (UTC+9; 2026-11-21 15:00 UTC) and returns HTTP 410 from then on. A bot meets the v2 spec when, over its last 10 minutes online, it makes no agent_poll call and opens at most 10 stream connections; a new bot is checked for 10 minutes and stays in automatic matching meanwhile, and a bot that did not meet it needs 10 clean minutes. From 2026-11-21 23:40 (UTC+9), registered bots that do not meet it are left out of automatic matching.",
                "parameters": [
                    {
                        "name": "state",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "1",
                                "0"
                            ]
                        },
                        "description": "Default (same as 1): send the state after hello and this bot's view (view \"agent\") in every match event, including invitations and games against people. 0: the older format (match notices only, no state)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "NDJSON events",
                        "content": {
                            "application/x-ndjson": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/StreamHello"
                                        },
                                        {
                                            "$ref": "#/components/schemas/StreamState"
                                        },
                                        {
                                            "$ref": "#/components/schemas/StreamMatch"
                                        },
                                        {
                                            "$ref": "#/components/schemas/StreamPing"
                                        },
                                        {
                                            "$ref": "#/components/schemas/StreamClosing"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "invalid bot credential",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "const": false
                                        },
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "bot match storage unavailable",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "const": false
                                        },
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}